Domains

Consolidated domain provisioning — atomically creates port + DNS + reverse proxy in a single call.

Create a domain (port + DNS + proxy in one call)

POST

/api/v1

/projects/{projectId}/stacks/{stackId}/domains

auth_token (cookie)

Bearer

Atomically provisions an exposed (internal-only) port, a DNS record with TLS, and a reverse proxy connecting them. Two flavors:

Custom domain (managed: false): requires dns to be a user-owned hostname whose CNAME points to the platform gateway. A pre-flight CNAME check runs server-side.
Managed subdomain (managed: true): allocates a random *.<MANAGED_DOMAIN_BASE> subdomain. Subject to a per-org quota.

On any failure during creation, all already-created resources are rolled back (proxy → expose → port row → dns row, on both backbone and DB) before returning the error.

Create a domain (port + DNS + proxy in one call) › path Parameters

projectId

string · uuid · required

Project unique identifier

stackId

string · uuid · required

Stack unique identifier

Create a domain (port + DNS + proxy in one call) › Request Body

CreateDomainRequest

managed

boolean · required

If true, allocate a random *.<MANAGED_DOMAIN_BASE> subdomain. If false, dns is required and a CNAME check is performed.

port

integer · int32 · min: 1 · max: 65535 · required

Internal container port to expose. Must be declared in the compose ports: or carry an fr.composerun.routedPort.<port> label.

Example: 8080

dns

string

Custom domain (required when managed is false). Ignored when managed is true.

Example: app.example.com

origin

string

Optional free-text origin label persisted on the DNS row.

tls_enable

boolean

Default: false

tls_force

boolean

Default: false

Create a domain (port + DNS + proxy in one call) › Responses

Domain created (port + DNS + proxy)

CreateDomainResponse

PortExposeResponse

DnsResponse

POST/projects/{projectId}/stacks/{stackId}/domains

curl /api/v1/projects/:projectId/stacks/:stackId/domains \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "managed": true,
  "dns": "app.example.com",
  "origin": "origin",
  "port": 8080,
  "tls_enable": false,
  "tls_force": false
}'

Example Request Body

{
  "managed": true,
  "dns": "app.example.com",
  "origin": "origin",
  "port": 8080,
  "tls_enable": false,
  "tls_force": false
}

json

Example Responses

{
  "port": {
    "id": "00000000-0000-0000-0000-000000000000",
    "stack_id": "00000000-0000-0000-0000-000000000000",
    "internal_port": 0,
    "infra_id": "infra_id",
    "is_public": true,
    "public_port": 0,
    "proxy_id": "proxy_id",
    "dns_id": "00000000-0000-0000-0000-000000000000",
    "tls_enabled": true,
    "tls_force": true,
    "created_at": "2024-08-25T15:00:00Z"
  },
  "dns": {
    "id": "00000000-0000-0000-0000-000000000000",
    "domain": "myapp.example.com",
    "infraId": "infraId"
  }
}

json

application/json

Delete a domain (cascades proxy + port + DNS)

DELETE

/api/v1

/projects/{projectId}/stacks/{stackId}/domains/{dnsId}

auth_token (cookie)

Bearer

Reverses a POST /domains: deletes the reverse proxy, the exposed port, and the DNS record on both the backbone and the DB. Best-effort on partial backbone failures — only a final DB DeleteDns failure returns a 5xx; intermediate backbone errors are logged and surfaced via OTel.

Delete a domain (cascades proxy + port + DNS) › path Parameters

projectId

string · uuid · required

Project unique identifier

stackId

string · uuid · required

Stack unique identifier

dnsId

string · uuid · required

DNS record UUID

Delete a domain (cascades proxy + port + DNS) › Responses

Domain deleted

No data returned

Webhooks