Developers
Developer Portal

API reference

Deployments

List deployments, read build and runtime logs, redeploy and promote.
Read the Guide
POST/v1/protection/token

A two-minute sign-in link to a protected host for the signed-in person: a deployment's own URL, or the production host or a custom domain of a project that protects everything. They need deployments:read in its organization and, when the project limits it to groups, to be in one of them or an owner or admin. People only, not keys.

Auth
A person's token or an API key, as Authorization: Bearer.
Allowed
deployments:read
Get an API key

Request body

  • hoststringrequired

    1–253 characters. Trimmed.

  • nextstring

    Up to 2,048 characters.

Errors

  • 403Only people can open protected deployments.
  • 403You don't have access to this deployment. Ask an owner of its organization to invite you.
  • 403Only members of the groups this Serverless App Service names can open it. Ask an owner or admin of its organization.
  • 404Deployment not found.
curl -X POST 'https://api.cactive.com.au/v1/protection/token' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  url: string
}
POST/v1/orgs/:orgId/projects/:projectId/uploads

A presigned PUT URL (15 minutes) for one source archive of size bytes (gzipped tar, at most 250 MB). Send the archive with exactly the returned headers, then start a deployment with the uploadId.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
deployments:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • projectId

    Serverless App Service id (prj_…).

Request body

  • sizeintegerrequired

    1–262144000.

Errors

  • 404Serverless App Service not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/projects/{projectId}/uploads' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "size": 1
  }'
Send it from this page with your session or a key.

Response 201

{
  uploadId: string
  url: string
  headers: {
    "content-type": string
    "content-length": string
  }
  expiresIn: number
}
POST/v1/orgs/:orgId/projects/:projectId/uploads/plan

Plans an upload from the working tree's index (files: path → "<mode> <blob id>", at most 50,000). skip: a ready deployment of the same files and build inputs (none with force); else base and need: an earlier full upload to send only the changed files on top of; else neither (upload it whole). Writes nothing.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
deployments:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • projectId

    Serverless App Service id (prj_…).

Request body

  • target"production" | "preview"required
  • filesobjectrequired

    Values: string.

  • forceboolean

    Default false.

Errors

  • 400The file list can't be used (over 50,000 files, or odd paths): upload the whole tree.
  • 404Serverless App Service not found
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/projects/{projectId}/uploads/plan' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "target": "production",
    "files": {}
  }'
Send it from this page with your session or a key.

Response 200

{
  tree: string
  skip: {
    deploymentId: string
    host?: string
  }
}
| {
  tree: string
}
| {
  tree: string
  base: {
    uploadId: string
  }
  need: string[]
}
POST/v1/orgs/:orgId/projects/:projectId/deployments

Starts a deployment of the Serverless App Service. git: a commit of the linked repository on branch, with target (default: production for the production branch, else preview); a commit that already has a building or ready deployment for that target returns it (200) unless force. upload: the archive uploaded with uploadId, built as target.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
deployments:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • projectId

    Serverless App Service id (prj_…).

Request body

  • source"git" | "upload"required
  • branchstring

    1–255 characters. Trimmed.

  • commitShastring

    Matches ^[0-9a-f]{40}$.

  • uploadIdstring

    Matches ^up_[A-Za-z0-9_-]{16,64}$.

  • target"production" | "preview"
  • forceboolean

    Default false.

  • manifestobject

    Values: any JSON.

  • filesobject

    Values: string.

  • basestring

    Matches ^up_[A-Za-z0-9_-]{16,64}$.

  • skipstring

    1–64 characters.

  • metaobject
  • meta.branchstring

    Up to 255 characters.

  • meta.commitstring

    Matches ^[0-9a-f]{7,40}$.

  • meta.dirtyboolean
  • meta.machinestring

    Up to 64 characters.

Errors

  • 400A git deployment needs branch and commitSha.
  • 400An upload deployment needs a target.
  • 400The file list can't be used (over 50,000 files, or odd paths).
  • 400A skip needs the file list.
  • 400An upload deployment needs uploadId and target.
  • 400A delta needs the file list.
  • 404Serverless App Service not found
  • 404Not found
  • 404Commit not found
  • 409Link a repository to this Serverless App Service first.
  • 409Something changed since the plan: upload the files.
  • 409The upload wasn't found. Upload the archive first.
  • 409The base upload is gone or isn't a full upload: upload the whole tree.
  • 413The archive is larger than 250 MB.
  • 502Couldn't start the build. Try again.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/projects/{projectId}/deployments' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "git"
  }'
Send it from this page with your session or a key.

Response 200

{
  deployment: {
    deploymentId: string
    host?: string
    target: "preview" | "production"
  }
  existing: true
}

Response 201

{
  deployment: {
    deploymentId: string
    host: string
    target: "preview" | "production"
  }
  existing: false
}
| {
  deployment: {
    deploymentId: string
    host?: string
    target: "preview" | "production"
  }
  existing: false
  skipped: true
}
GET/v1/orgs/:orgId/deployments/:deploymentId/build-log

Build output after cursor (from the first step on), with the deployment's status. Poll with the returned cursor until done: the deployment has finished and no output is left.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
logs:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • deploymentId

    Deployment id (dpl_…).

Query parameters

  • cursorstring

    Up to 2,048 characters.

Errors

  • 404Deployment not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/deployments/{deploymentId}/build-log' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  lines: []
  cursor: null | string
  status: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
  error: null | string
  done: boolean
}
| {
  status: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
  error: null | string
  done: boolean
  lines: {
    t: number
    m: string
  }[]
  cursor: string
}
GET/v1/orgs/:orgId/deployments/:deploymentId/runtime-logs/tail

Server function log events from since (epoch ms, at most an hour back; default the last minute) to now, oldest first, with event ids. q filters case-insensitively. Poll again from next, re-reading a few seconds (late events) and skipping ids already seen.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
logs:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • deploymentId

    Deployment id (dpl_…).

Query parameters

  • sinceinteger

    ≥ 0. Coerced from a string.

  • qstring

    Up to 200 characters. Trimmed.

Errors

  • 404Deployment not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/deployments/{deploymentId}/runtime-logs/tail' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  available: false
  lines: []
  next: number
  more: false
}
| {
  lines: {
    id: string
    t: number
    level: "error" | "platform" | "warn" | "info" | "debug"
    requestId?: string
    message: string
    truncated?: boolean
  }[]
  next: number
  more: boolean
  available: true
}
GET/v1/orgs/:orgId/deployments

Lists deployments across Serverless App Services, newest first. Pass the returned cursor to get the next page.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
deployments:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Query parameters

  • projectIdstring

    At least 1 character.

  • target"production" | "preview"
  • status"queued" | "building" | "deploying" | "ready" | "error" | "canceled" | "expired" | "skipped"
  • branchstring

    1–255 characters.

  • cursorstring

    At least 1 character.

  • limitinteger

    Default 50. 1–100. Coerced from a string.

Errors

  • 404Serverless App Service not found
  • 404Not found
  • 404Commit not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/deployments' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  deployments: {
    region?: string
    error?: string
    status?: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
    createdAt?: number
    updatedAt?: number
    orgId: string
    createdBy?: string
    projectId: string
    reason?: string
    location: string
    edgeOnly?: boolean
    deploymentId: string
    target: "preview" | "production"
    branch?: string
    commitSha?: string
    commitMessage?: string
    commitAuthor?: string
    host?: string
    buildId?: string
    cacheBuildId?: string
    edgeGen?: string
    server?: "node"
    buildLogGroup?: string
    builtOrgId?: string
    buildDurationMs?: number
    deployClaimedAt?: number
    deployClaimedBy?: string
    readyAt?: number
    envTarget?: "preview" | "production"
    memoryMb?: number
    timeoutSeconds?: number
    crons?: string
    envHash?: string
    previousDeploymentId?: string
    source?: "git" | "upload"
    sourceArchive?: string
    sourceBase?: string
    sourceTree?: string
    sourceManifest?: string
    buildMetrics?: {
      restoreMs?: number
      installMs?: number
      buildMs?: number
      uploadMs?: number
      saveMs?: number
      depsCache?: "off" | "hit" | "partial" | "miss"
      nextCache?: "off" | "hit" | "partial" | "miss"
      packageManager?: string
      installDir?: string
    }
  }[]
  cursor: null | string
}
GET/v1/orgs/:orgId/deployments/:deploymentId

A deployment and a summary of its Serverless App Service.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
deployments:read
Allowed
domains:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • deploymentId

    Deployment id (dpl_…).

Errors

  • 404Deployment not found
  • 404Serverless App Service not found
  • 404Not found
  • 404Commit not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/deployments/{deploymentId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  deployment?: {
    region?: string
    error?: string
    status?: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
    createdAt?: number
    updatedAt?: number
    orgId: string
    createdBy?: string
    projectId: string
    reason?: string
    location: string
    edgeOnly?: boolean
    deploymentId: string
    target: "preview" | "production"
    branch?: string
    commitSha?: string
    commitMessage?: string
    commitAuthor?: string
    host?: string
    buildId?: string
    cacheBuildId?: string
    edgeGen?: string
    server?: "node"
    buildLogGroup?: string
    builtOrgId?: string
    buildDurationMs?: number
    deployClaimedAt?: number
    deployClaimedBy?: string
    readyAt?: number
    envTarget?: "preview" | "production"
    memoryMb?: number
    timeoutSeconds?: number
    crons?: string
    envHash?: string
    previousDeploymentId?: string
    source?: "git" | "upload"
    sourceArchive?: string
    sourceBase?: string
    sourceTree?: string
    sourceManifest?: string
    buildMetrics?: {
      restoreMs?: number
      installMs?: number
      buildMs?: number
      uploadMs?: number
      saveMs?: number
      depsCache?: "off" | "hit" | "partial" | "miss"
      nextCache?: "off" | "hit" | "partial" | "miss"
      packageManager?: string
      installDir?: string
    }
  }
  project: {
    projectId: string
    name: string
    slug: string
    productionDeploymentId?: string
    repoId?: string
    framework?: "static" | "nextjs" | "node"
    location: string
    rootDirectory?: string
  }
  productionHost?: string
  domains?: {
    hostname: string
    status?: "error" | "active" | "pending" | "verifying"
    redirectTo?: string
  }[]
  function: null | {
    region: string
    name: string
    memoryMb: number
    timeoutSeconds: number
    architecture: "arm64"
    runtime: "nodejs22.x"
  }
}
GET/v1/orgs/:orgId/deployments/:deploymentId/logs

Build output, starting at the first build step.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
logs:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • deploymentId

    Deployment id (dpl_…).

Errors

  • 404Deployment not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/deployments/{deploymentId}/logs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  lines: {
    t?: number
    m: string
  }[]
}
GET/v1/orgs/:orgId/deployments/:deploymentId/runtime-logs

Server function logs, newest first, at most 500 per page. range (1h, 6h, 24h, 7d; default 1h) bounds how far back; pass the returned older as before for the next page; after returns only newer events (live tail). q filters messages case-insensitively. available is false for deployments without a server function.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
logs:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • deploymentId

    Deployment id (dpl_…).

Query parameters

  • qstring

    Up to 200 characters. Trimmed.

  • rangeany
  • beforeinteger

    > 0. Coerced from a string.

  • afterinteger

    > 0. Coerced from a string.

Errors

  • 404Deployment not found
curl 'https://api.cactive.com.au/v1/orgs/{orgId}/deployments/{deploymentId}/runtime-logs' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  available: false
  lines: []
}
| {
  older?: number
  lines: {
    id?: string
    t: number
    level: "error" | "platform" | "warn" | "info" | "debug"
    requestId?: string
    message: string
    truncated?: boolean
  }[]
  from: number
  to: number
  limited: boolean
  available: true
}
POST/v1/orgs/:orgId/deployments/:deploymentId/redeploy

Builds the deployment's commit again as a new deployment with the same target.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
deployments:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • deploymentId

    Deployment id (dpl_…).

Errors

  • 404Deployment not found
  • 404Serverless App Service not found
  • 409This deployment is still in progress.
  • 409This upload has expired. Deploy again from your terminal.
  • 409This deployment has no commit to build.
  • 409Link a repository to this Serverless App Service first.
  • 502Couldn't start the build. Try again.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/deployments/{deploymentId}/redeploy' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 201

{
  deployment: {
    deploymentId: string
    host: string
    target: "preview" | "production"
  }
}
POST/v1/orgs/:orgId/deployments/:deploymentId/promote

Makes a ready deployment production without rebuilding: promotes a preview, or rolls back to an earlier production deployment. A promoted preview's function switches to production's variables unless the body is { "env": "preview" }. A rollback holds production there: new production builds don't go live until a deployment is promoted.

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
deployments:write
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

  • deploymentId

    Deployment id (dpl_…).

Errors

  • 400Invalid request.
  • 404Deployment not found
  • 404Serverless App Service not found
  • 409This deployment has expired. Redeploy it instead.
  • 409Only ready deployments can be promoted.
  • 409This is already the production deployment.
  • 409This deployment's server function was removed. Redeploy it instead.
  • 502Couldn't apply the production environment variables. Production wasn't changed; try again.
  • 502Couldn't update production routing. Try again.
curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/deployments/{deploymentId}/promote' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  deployment: {
    region?: string
    error?: string
    status?: "error" | "queued" | "building" | "deploying" | "ready" | "canceled" | "expired" | "skipped"
    createdAt?: number
    updatedAt?: number
    orgId: string
    createdBy?: string
    projectId: string
    reason?: string
    location: string
    edgeOnly?: boolean
    deploymentId: string
    target: "preview" | "production"
    branch?: string
    commitSha?: string
    commitMessage?: string
    commitAuthor?: string
    host?: string
    buildId?: string
    cacheBuildId?: string
    edgeGen?: string
    server?: "node"
    buildLogGroup?: string
    builtOrgId?: string
    buildDurationMs?: number
    deployClaimedAt?: number
    deployClaimedBy?: string
    readyAt?: number
    envTarget?: "preview" | "production"
    memoryMb?: number
    timeoutSeconds?: number
    crons?: string
    envHash?: string
    previousDeploymentId?: string
    source?: "git" | "upload"
    sourceArchive?: string
    sourceBase?: string
    sourceTree?: string
    sourceManifest?: string
    buildMetrics?: {
      restoreMs?: number
      installMs?: number
      buildMs?: number
      uploadMs?: number
      saveMs?: number
      depsCache?: "off" | "hit" | "partial" | "miss"
      nextCache?: "off" | "hit" | "partial" | "miss"
      packageManager?: string
      installDir?: string
    }
  }
  productionHost: string
  productionHold: boolean
}
GET/v1/orgs/:orgId/deployment-hosts

After a slug change: the slug the deployment hosts use (deploymentSlug), where a move takes them (move, with moving when one didn't finish), each Serverless App Service's production host before and after (conflict when the new one belongs to someone else), and the old hosts still serving (former).

Auth
A person's token or an API key, as Authorization: Bearer.
Scope
deployments:read
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/deployment-hosts' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  nextAttemptAt?: number
  slug: string
  deploymentSlug: string
  move: null | {
    moving: boolean
    from: string
    to: string
  }
  projects: {
    projectId: string
    name: string
    from: string
    to: string
    conflict?: true
  }[]
  former: {
    name?: string
    host: string
    projectId: string
  }[]
}
POST/v1/orgs/:orgId/deployment-hosts/move

Moves the production hosts to the organisation's slug, or finishes a move that stopped. The old hosts keep serving production. Owners only, acting themselves; once a minute (429 with Retry-After). state is unfinished when services are left for the next attempt.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/deployment-hosts/move' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  state: "done" | "unfinished"
  from: string
  to: string
  moved: {
    projectId: string
    name: string
    from: string
    to: string
  }[]
  left: {
    projectId: string
    name: string
    reason: string
  }[]
  redirects: {
    added: number
    left: {
      clientId: string
      name: string
      uris: string[]
    }[]
  }
}
DELETE/v1/orgs/:orgId/deployment-hosts/former

Stops serving the old production hosts (all, or each host given). The names stay the organisation's. Owners only, acting themselves.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • orgId

    Organization id (org_…).

Query parameters

  • hoststring | string[]

Errors

  • 400Name at most 200 addresses at once.
curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/deployment-hosts/former' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  removed: string[]
  busy: string[]
}