Get project

Read a project and its services in one environment. Select an environment explicitly when automating a workflow.

GET /api/projects/{slug} HTTPS

Request & response examples

Request example Server-side

curl --fail-with-body --request GET \
  'https://app.helicarrier.xyz/api/projects/my-project?env=staging' \
  -H "Authorization: Bearer $HELI_API_KEY"

const response = await fetch(
  "https://app.helicarrier.xyz/api/projects/my-project?env=staging",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.HELI_API_KEY}`
    }
  }
);
const data = await response.json();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${data.error}`);
}
// Inspect data; avoid logging secret responses.

import os
import requests

response = requests.request(
    "GET",
    "https://app.helicarrier.xyz/api/projects/my-project?env=staging",
    headers={
        "Authorization": f"Bearer {os.environ['HELI_API_KEY']}"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
# Inspect data; avoid logging secret responses.

Response example 200

{
  "project": {
    "id": "prj_example",
    "name": "My project",
    "slug": "my-project",
    "description": ""
  },
  "services": [
    {
      "id": "svc_example",
      "name": "my-app",
      "slug": "my-app",
      "sourceType": "image",
      "status": "running",
      "planKey": "heli-s1",
      "projectId": "prj_example",
      "environmentId": "env_example"
    }
  ],
  "environments": [
    {
      "id": "env_example",
      "projectId": "prj_example",
      "name": "Staging",
      "slug": "staging",
      "isDefault": false
    }
  ],
  "environment": {
    "id": "env_example",
    "projectId": "prj_example",
    "name": "Staging",
    "slug": "staging",
    "isDefault": false
  }
}

Illustrative values · selected fields

Response details ↓ OpenAPI ↗

Authorization

An account key with project access, or a project key for this project. Environment restrictions still apply.

Authorization: Bearer <key> Key setup ↗

Path parameters

slug string required

Project slug.

Query parameters

env string optional

Environment slug (e.g. dev, staging, production) whose services to return. Omit for the project's default environment — which is why a service you expect to see can be missing: it lives in another environment.

Response 200

Returns a project with the services for one environment. Omit env to use the default environment. A service in another environment will not appear in this result.

Examples show selected response fields with illustrative values. Your response can contain additional fields.

project object

Project metadata.

Child fields

id string
Unique identifier of this resource.
name string
Human-readable resource name.
slug string
URL-safe resource identifier.
description string
Description of the resource or capability.

services array

Services in the selected environment, or type previews in a project listing.

Child fields

id string
Unique identifier of this resource.
name string
Human-readable resource name.
slug string
URL-safe resource identifier.
sourceType string
Source used to build or run the service.
status string
Current state of the resource or operation.
planKey string
Plan identifier from the plan catalog.
projectId string
Project that owns the resource.
environmentId string
Environment that contains the service.

environments array

Environments visible to the caller.

Child fields

id string
Unique identifier of this resource.
projectId string
Project that owns the resource.
name string
Human-readable resource name.
slug string
URL-safe resource identifier.
isDefault boolean

environment object

Environment selected for this response.

Child fields

id string
Unique identifier of this resource.
projectId string
Project that owns the resource.
name string
Human-readable resource name.
slug string
URL-safe resource identifier.
isDefault boolean

Errors

401

The API key is missing, invalid, or revoked.

403

The caller or key scope does not permit this operation.

404

The resource does not exist or is not visible to this caller.

500

The operation could not be completed. Check resource state before retrying a write.

Error handling and safe retries

ALSO AVAILABLE VIA MCP

`get_project`

Required MCP arguments: slug. Send path, query, and body fields together as tool arguments.

Connect your agent ↗