Commercial CI/CD

API token integration reference

Use scoped bearer tokens to automate runs, read deployment evidence, export workspace data, retry webhooks, and operate support workflows with least privilege.

View OpenAPI JSON

Authentication

Create API tokens in the app and send them as Authorization: Bearer ship_.... Tokens are scoped and cannot open browser pages. Account profile and browser session endpoints use the signed-in browser cookie (cookieAuth) and reject bearer tokens.

Scopes

Use explicit scopes such as runs:read, runs:write, approvals:read, approvals:write, deployments:read, deployments:write, runners:read, runners:write, billing:read, billing:write, support:read, exports:write, or outbound-webhooks:write. Wildcard scopes are not honored.

Errors

Authentication, scope, browser-session, payload-size, and selected handled application errors use application/problem+json and include X-Request-Id. Worker and endpoint validation may return simpler JSON error objects; CSRF failures return plain text.

OpenAPI

The machine-readable endpoint reference is available at /api/openapi.json. The metadata endpoint at /api lists supported scopes and public webhook endpoints.

Problem Types

/docs/api#errors-invalid-api-token: bearer token is invalid or revoked.

/docs/api#errors-session-expired: browser session is expired, revoked, or belongs to an inactive user.

/docs/api#errors-browser-session-required: account APIs require a signed-in browser session instead of bearer token auth.

/docs/api#errors-insufficient-scope: bearer token lacks the required least-privilege scope.

/docs/api#errors-authentication-required: endpoint requires authentication.

/docs/api#errors-payload-too-large: request body exceeds the API limit.

/docs/api#errors-action-needed: a selected handled application or validation failure; details receive best-effort secret-pattern masking before support use.

Shipline Git and Registry

Use git:read and git:write for Shipline Git clone/fetch/push operations. Use registry:read and registry:write for Docker pull, push, tag deletion, catalog, and blob-mount operations against Shipline Registry.

Agent Task API scopes

Use agent-tasks:read and agent-tasks:write for task intake and review. Use agent-tasks:approve for approval-gated branch/PR work. OpenCode workers also need agent-tasks:worker for claim, renew, logs, validations, and completion.

Hosted Canary Automation

Use an API token with support:write,support:read,runs:read for scripts/validate-hosted-canary.ps1 so it can queue the canary and read its run-output evidence.

Automation launch checklist

Split tokens: create one API token per workflow, environment, and automation owner.

Start read-only: grant write scopes only to workflows that need to mutate runs, approvals, deployments, registry tags, Agent Tasks, or support operations.

Rotate: revoke ownerless tokens before live canaries, launch evidence capture, and customer onboarding.

Scope bundle guide

Run evidence botruns:read
Release approval botruns:read,approvals:write,deployments:read
Registry cleanup botregistry:read,registry:write
Agent Task workeragent-tasks:read,agent-tasks:write,agent-tasks:worker
Agent Task canary botagent-tasks:read,agent-tasks:write,agent-tasks:approve,agent-tasks:worker,billing:read,support:read
Workspace export botexports:write
Hosted canary botsupport:write,support:read,runs:read

Workflow Examples

Queue a run with POST /api/pipelines/{pipelineId}/runs, approve a deployment with POST /api/approvals/{approvalId}/approve, list release-artifact metadata with GET /api/runs/{runId}/artifacts, delete a registry tag through POST /api/registry/delete, generate a workspace export with POST /api/exports/workspace and receive its safe artifact-storage reference rather than a direct file download, and request hosted runner access with POST /api/billing/hosted-access/request.

curl -H "Authorization: Bearer ship_..." https://ci.company.com/api/runs/{runId}/artifacts
curl -X POST -H "Authorization: Bearer ship_..." -H "Content-Type: application/json" --data '{"comment":"Approved after evidence review"}' https://ci.company.com/api/approvals/{approvalId}/approve
curl -X POST -H "Authorization: Bearer ship_..." https://ci.company.com/api/support/hosted-canary