Create service

Create a service from a Git repository or container image. Creation queues a deployment and starts a billed resource.

POST /api/services HTTPS

Request & response examples

Request example Server-side

curl --fail-with-body --request POST \
  'https://app.helicarrier.xyz/api/services' \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "name": "my-app",
  "projectSlug": "my-project",
  "environmentSlug": "staging",
  "image": "nginx:stable",
  "internalPort": 80,
  "planKey": "heli-s1"
}'

const response = await fetch(
  "https://app.helicarrier.xyz/api/services",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.HELI_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "my-app",
      "projectSlug": "my-project",
      "environmentSlug": "staging",
      "image": "nginx:stable",
      "internalPort": 80,
      "planKey": "heli-s1"
    })
  }
);
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(
    "POST",
    "https://app.helicarrier.xyz/api/services",
    headers={
        "Authorization": f"Bearer {os.environ['HELI_API_KEY']}"
    },
    json={
      "name": "my-app",
      "projectSlug": "my-project",
      "environmentSlug": "staging",
      "image": "nginx:stable",
      "internalPort": 80,
      "planKey": "heli-s1"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
# Inspect data; avoid logging secret responses.

Response example 201

{
  "id": "svc_example",
  "name": "my-app",
  "slug": "my-app",
  "sourceType": "image",
  "status": "idle",
  "planKey": "heli-s1",
  "projectId": "prj_example",
  "environmentId": "env_example"
}

Illustrative values · selected fields

Response details ↓ OpenAPI ↗

Authorization

An account key with access, or a project key with project:write. A service key cannot perform this operation.

Authorization: Bearer <key> Key setup ↗

Request body application/json

name string required

Service name.

projectSlug string optional

Target project slug. Set this explicitly for automation; project keys require their own project. An account key that omits it uses the default project, if one exists.

environmentSlug string optional

Target environment slug (e.g. dev, staging, production). Optional for a normal key — the project's default environment is used. REQUIRED when your API key is restricted to specific environments; call whoami to see whether yours is.

repoUrl string optional

Git repo URL (for source builds).

image string optional

Docker image ref (for image services).

internalPort integer optional

Port the app listens on.

planKey string optional

Plan key from list_plans (e.g. heli-s1). Prefer passing this explicitly so the service runs on the intended plan; if omitted, the cheapest plan matching the service type is applied.

Response 201

Creation also queues a deployment and starts a billed resource. Choose a plan before creating the service. Supply either a Git repository or a container image.

Examples show selected response fields with illustrative values. Your response can contain additional 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.

Errors

400

Invalid parameters. Check the required fields, types, and resource configuration.

401

The API key is missing, invalid, or revoked.

402

The account must resolve a billing requirement before continuing.

403

The caller or key scope does not permit this operation.

404

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

Error handling and safe retries

ALSO AVAILABLE VIA MCP

`create_service`

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

Connect your agent ↗