API quickstart

The Helicarrier Cloud API lets you work with projects, services, deployments, variables, networking, and data services from scripts and CI. The hosted MCP integration uses the same underlying operations and authorization checks.

Base URL: https://app.helicarrier.xyz

Authentication: Authorization: Bearer <API key>

Download the OpenAPI 3.1 specification to explore the documented automation surface in your API tooling. This reference covers the REST operations exposed by the MCP catalog, plus documented REST pagination parameters. It does not describe private operator or administration endpoints.

1. Create a key

Create a key in the dashboard. Read Authentication to choose its type and scope. Use a project or service key for a bounded workflow, or an account key when the operation requires account-level access. A key never grants more access than its creator has.

Store the key in a local environment variable or your CI secret store. These examples assume HELI_API_KEY already contains your key. Do not put the real value in source code, a shared config, or a command you will publish.

2. Identify your scope

curl --fail-with-body \
  'https://app.helicarrier.xyz/api/auth/me' \
  -H "Authorization: Bearer $HELI_API_KEY"

The identity response reports the caller and any key scope. A service key cannot list the entire account; use its service ID from this response. A project key may restrict you to selected environments.

3. Read the right project and environment

For an account key, list projects:

curl --fail-with-body \
  'https://app.helicarrier.xyz/api/projects' \
  -H "Authorization: Bearer $HELI_API_KEY"

Then read a project by slug, choosing the environment explicitly:

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

The project response contains services for one environment. If you omit env, it uses the project’s default. The project-list response’s services field is only a preview of types for dashboard cards; use Get project for full service records.

4. Trigger a deployment

Use a key with deployment write access to the chosen service. Replace YOUR_SERVICE_ID with its real ID:

curl --fail-with-body --request POST \
  'https://app.helicarrier.xyz/api/services/YOUR_SERVICE_ID/deploy' \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"ref":"main"}'

An accepted request returns HTTP 202. Example response shape:

{
  "deploymentId": "DEPLOYMENT_ID",
  "ref": "main"
}

ref is optional for Git services and selects a one-off branch, tag, or commit. It does not change the tracked branch. For an image service, omit the Git ref.

5. Follow the result

An accepted request queues work; it is not a successful deployment. Read the service’s deployment list and the new deployment’s logs:

curl --fail-with-body \
  'https://app.helicarrier.xyz/api/services/YOUR_SERVICE_ID/deployments?limit=25' \
  -H "Authorization: Bearer $HELI_API_KEY"

curl --fail-with-body \
  'https://app.helicarrier.xyz/api/deployments/DEPLOYMENT_ID/logs?after=0' \
  -H "Authorization: Bearer $HELI_API_KEY"

Deployment history returns an object with deployments and nextCursor. Build logs return an array. See pagination and logs for incremental reads.

JavaScript example

This server-side helper reads a service and preserves the HTTP status in errors. It never sends the key to a browser.

const baseURL = 'https://app.helicarrier.xyz';
const key = process.env.HELI_API_KEY;
if (!key) throw new Error('HELI_API_KEY is required');

async function getService(serviceId) {
  const response = await fetch(
    `${baseURL}/api/services/${encodeURIComponent(serviceId)}`,
    { headers: { Authorization: `Bearer ${key}` } }
  );
  const body = await response.json();
  if (!response.ok) {
    throw new Error(`Helicarrier ${response.status}: ${body.error ?? 'Request failed'}`);
  }
  return body;
}

Explore the reference

Resource	What you can do
Identity & plans	Discover scope and available plans
Projects & environments	Find projects and read services in an environment
Services	Create, configure, scale, stop, or remove a service
Deployments	Deploy, upload, roll back, and control triggers
Logs & metrics	Follow build output and inspect runtime behavior
Variables & references	Set variables and link services
Domains & networking	Manage domains, HTTP ports, and outbound IP attachments
Databases & storage	Discover engines, provision data services, and manage backups
Scheduled jobs	Inspect and run cron services

Compatibility

The API currently uses unversioned /api/ paths. Ignore response fields your client does not use, check HTTP status codes, and read the operation reference before automating a mutation. Do not assume a global pagination envelope or automatic idempotency support.

The downloadable schema describes the documented automation inputs. Some REST handlers accept additional dashboard-specific settings; those are not a promise of support in this automation reference. The MCP tool reference calls out the inputs available through MCP.