Create a service from an upload

Create a new service from a base64-encoded source archive. Use reupload to update an existing upload service.

POST/api/projects/{projectSlug}/services/upload-b64HTTPS

Request & response examples

Request exampleServer-side

curl --fail-with-body --request POST \
  'https://app.helicarrier.xyz/api/projects/my-project/services/upload-b64?env=staging' \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "name": "my-service",
  "archiveBase64": "BASE64_ENCODED_SOURCE_ARCHIVE"
}'

const response = await fetch(
  "https://app.helicarrier.xyz/api/projects/my-project/services/upload-b64?env=staging",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.HELI_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "my-service",
      "archiveBase64": "BASE64_ENCODED_SOURCE_ARCHIVE"
    })
  }
);
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/projects/my-project/services/upload-b64?env=staging",
    headers={
        "Authorization": f"Bearer {os.environ['HELI_API_KEY']}"
    },
    json={
      "name": "my-service",
      "archiveBase64": "BASE64_ENCODED_SOURCE_ARCHIVE"
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
# Inspect data; avoid logging secret responses.

Response example201

{
  "service": {
    "id": "svc_example",
    "name": "my-app",
    "slug": "my-app",
    "sourceType": "upload",
    "status": "running",
    "planKey": "heli-s1",
    "projectId": "prj_example",
    "environmentId": "env_example"
  },
  "deploymentId": "dep_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

Path parameters

projectSlugstringrequired

Target project slug.

Query parameters

envstringoptional

Target environment slug (e.g. dev, staging, production). This route takes the environment as a query argument, not in the body. 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.

Request bodyapplication/json

namestringrequired

Service name.

runtimeModestringoptional

web | worker | static | cron (default web).

archiveBase64stringrequired

The build context as a base64-encoded .tar.gz (or .zip) of your project folder.

rootDirstringoptional

Subdir the app lives in (optional).

installCommandstringoptional

Install override (optional).

buildCommandstringoptional

Build override (optional).

startCommandstringoptional

Start command / for static, the output dir (optional).

internalPortintegeroptional

Port the app listens on (optional).

planKeystringoptional

Plan key from list_plans (e.g. heli-static). 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

This creates a new service each time. To ship a new version to an existing upload service, use Reupload service instead. Exclude dependencies and repository metadata from the archive.

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

serviceobject

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.

deploymentIdstring

Identifier to use when reading deployment history or logs.

Errors

400

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

401

The API key is missing, invalid, or revoked.

403

The caller or key scope does not permit this operation.

409

The current resource state prevents the operation. Inspect it before retrying.

500

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

Error handling and safe retries

ALSO AVAILABLE VIA MCP

`deploy_upload`

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

Connect your agent