Environment and Domains API

Environment variables and domains belong to services.

All examples assume:

export AEROPLANE_URL="https://pilot.example.com"
export AEROPLANE_API_KEY="ap_..."

Set Environment Variable

POST /api/services/:serviceId/env

Required access: write

Project scope: service project must be visible to the key.

Payload:

{
  "key": "NODE_ENV",
  "value": "production"
}

Example:

curl -X POST "$AEROPLANE_URL/api/services/svc_web/env" \
  -H "Authorization: Bearer $AEROPLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"NODE_ENV","value":"production"}'

Response:

{
  "ok": true
}

The same endpoint creates or updates a variable. Environment variable keys must match:

^[A-Z_][A-Z0-9_]*$

Delete Environment Variable

DELETE /api/services/:serviceId/env/:envId

Required access: write

Project scope: service project must be visible to the key.

Example:

curl -X DELETE "$AEROPLANE_URL/api/services/svc_web/env/env_123" \
  -H "Authorization: Bearer $AEROPLANE_API_KEY"

Response:

{
  "ok": true
}

Add Domain

POST /api/services/:serviceId/domains

Required access: write

Project scope: service project must be visible to the key.

Workers do not accept custom domains.

Payload:

{
  "hostname": "app.example.com"
}

Example:

curl -X POST "$AEROPLANE_URL/api/services/svc_web/domains" \
  -H "Authorization: Bearer $AEROPLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"app.example.com"}'

Response:

{
  "ok": true,
  "caddy": {
    "ok": true,
    "detail": "Caddy reloaded"
  }
}

The created domain appears in GET /api/services/:serviceId/overview.

Update Domain

PATCH /api/services/:serviceId/domains/:domainId

Required access: write

Payload:

{
  "hostname": "www.example.com"
}

Response:

{
  "ok": true,
  "caddy": {
    "ok": true,
    "detail": "Caddy reloaded"
  }
}

Delete Domain

DELETE /api/services/:serviceId/domains/:domainId

Required access: write

Example:

curl -X DELETE "$AEROPLANE_URL/api/services/svc_web/domains/domain_123" \
  -H "Authorization: Bearer $AEROPLANE_API_KEY"

Response:

{
  "ok": true,
  "caddy": {
    "ok": true,
    "detail": "Caddy reloaded"
  }
}

Apply DNS Provider Record

POST /api/services/:serviceId/domains/:domainId/dns-records

Required access: write

Project scope: service project must be visible to the key.

This endpoint uses a DNS provider that has already been connected in System Settings.

Payload:

{
  "providerId": "cloudflare"
}

Supported provider IDs:

• cloudflare
• namecheap
• spaceship

Example:

curl -X POST "$AEROPLANE_URL/api/services/svc_web/domains/domain_123/dns-records" \
  -H "Authorization: Bearer $AEROPLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"cloudflare"}'

Response:

{
  "ok": true,
  "result": {
    "provider": "cloudflare",
    "providerName": "Cloudflare",
    "action": "created",
    "hostname": "app.example.com",
    "recordType": "A",
    "host": "app",
    "zone": "example.com",
    "targetIp": "203.0.113.10"
  },
  "domain": {
    "id": "domain_123",
    "serviceId": "svc_web",
    "hostname": "app.example.com",
    "status": "active",
    "createdAt": "2026-06-10T08:41:00.000Z",
    "updatedAt": "2026-06-10T08:42:00.000Z"
  }
}

Read Environment and Domains

Environment variables and domains are returned by service overview:

GET /api/services/:serviceId/overview

Response excerpt:

{
  "env": [
    {
      "id": "env_123",
      "key": "NODE_ENV",
      "hasValue": true,
      "value": "production",
      "resolvedValue": "production",
      "createdAt": "2026-06-10T08:40:00.000Z",
      "updatedAt": "2026-06-10T08:40:00.000Z"
    }
  ],
  "domains": [
    {
      "id": "domain_123",
      "serviceId": "svc_web",
      "hostname": "app.example.com",
      "status": "active",
      "createdAt": "2026-06-10T08:41:00.000Z",
      "updatedAt": "2026-06-10T08:42:00.000Z"
    }
  ]
}