API reference

Deployments

List deployments, read build and runtime logs, redeploy and promote.

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
}