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.
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 bot | runs:read |
| Release approval bot | runs:read,approvals:write,deployments:read |
| Registry cleanup bot | registry:read,registry:write |
| Agent Task worker | agent-tasks:read,agent-tasks:write,agent-tasks:worker |
| Agent Task canary bot | agent-tasks:read,agent-tasks:write,agent-tasks:approve,agent-tasks:worker,billing:read,support:read |
| Workspace export bot | exports:write |
| Hosted canary bot | support: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