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 exampleServer-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 example200

{
  "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

slugstringrequired

Project slug.

Query parameters

envstringoptional

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.

projectobject

Project metadata.

Child fields

idstring
Unique identifier of this resource.
namestring
Human-readable resource name.
slugstring
URL-safe resource identifier.
descriptionstring
Description of the resource or capability.

servicesarray

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

Child fields

idstring
Unique identifier of this resource.
namestring
Human-readable resource name.
slugstring
URL-safe resource identifier.
sourceTypestring
Source used to build or run the service.
statusstring
Current state of the resource or operation.
planKeystring
Plan identifier from the plan catalog.
projectIdstring
Project that owns the resource.
environmentIdstring
Environment that contains the service.

environmentsarray

Environments visible to the caller.

Child fields

idstring
Unique identifier of this resource.
projectIdstring
Project that owns the resource.
namestring
Human-readable resource name.
slugstring
URL-safe resource identifier.
isDefaultboolean

environmentobject

Environment selected for this response.

Child fields

idstring
Unique identifier of this resource.
projectIdstring
Project that owns the resource.
namestring
Human-readable resource name.
slugstring
URL-safe resource identifier.
isDefaultboolean

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