Deployments API

The Deployments API drives a project's build-and-release lifecycle: it starts builds (from a linked git repo or an uploaded folder), reports status and logs, and handles the operations you run afterwards — redeploy, roll back, pin, cancel, restart, and resolve a partial-failure compose deploy. In the dashboard this is the deploy wizard and the Deployments tab; from the terminal it's openship deploy and openship deployment.

Endpoints

Trigger a git deploy

Redeploys an already-linked project from its git source. To deploy a local folder instead, use the upload flow that ends at /build/access.

POST /api/deployments

curl -X POST https://your-host/api/deployments \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"proj_123","branch":"main"}'

# Same thing from the CLI:
openship deploy --project proj_123 --branch main

Prepare (detect build config)

Side-effect-free: point it at a git repo or a local path and it returns the detected framework, package manager, and build/start commands so the wizard can pre-fill. Creates nothing.

POST /api/deployments/prepare

Deploy wizard (/build/access)

The wizard's Deploy button. Creates a fresh deployment and starts the build. For a folder-upload deploy, pass projectId (from projects/ensure) and uploadSessionId (from projects/folder/session); for a git project, pass projectId and optionally branch. Returns { success, deployment_id, project_id }.

POST /api/deployments/build/access

Each publicEndpoints entry is { port?, targetPath?, domain?, customDomain?, domainType? } where domainType is "free" or "custom". A services entry mirrors a compose/monorepo service (name, image?, build?, dockerfile?, ports, dependsOn, environment, volumes, and the optional per-app build fields).

curl -X POST https://your-host/api/deployments/build/access \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"proj_123","branch":"main","buildStrategy":"server"}'

Get status, logs, and stream

GET /api/deployments/:id
GET /api/deployments/:id/logs
GET /api/deployments/:id/stream

/:id returns the deployment's status, URLs, timing, and any error summary. /logs returns the recorded build/runtime output; /stream is a Server-Sent Events feed of the live build — reconnect to it with a ?since=<seq> cursor to resume where you left off.

openship deployment get <deploymentId>

Redeploy

Re-runs the build. By default it resolves the latest commit on the branch (the auto-redeploy semantic); send { "useExistingCommit": true } to rebuild against the exact commit the original deployment used.

POST /api/deployments/:id/redeploy

openship deployment redeploy <deploymentId>

Rollback and pin

Rollback restores a previous deployment's artifact/commit as the active release. Pinning marks a deployment as protected so it isn't reclaimed by the rollback-window cleanup — POST /:id/pin defaults to { "pinned": true }; send { "pinned": false } to unpin.

POST /api/deployments/:id/rollback
POST /api/deployments/:id/pin

openship deployment rollback <deploymentId>
openship deployment pin <deploymentId>

Cancel a running deploy

POST /api/deployments/:id/cancel

openship deployment cancel <deploymentId>

Partial-failure compose deploys: keep or reject

When a multi-service (compose) deploy has some services succeed and others fail, it is held in partial_failure with decision: pending ("Action Required"). Resolve it explicitly:

• Keep accepts the services that succeeded and leaves the rest on their prior version.
• Reject rolls back the changed services to their previous state.

POST /api/deployments/:id/keep
POST /api/deployments/:id/reject

openship deployment keep <deploymentId>
openship deployment reject <deploymentId>

SSL status and renew

Both take the domain in the JSON body. /ssl/status is a side-effect-free probe (POST only so the hostname travels in the body); /ssl/renew re-issues the certificate.

POST /api/deployments/ssl/status
POST /api/deployments/ssl/renew

curl -X POST https://your-host/api/deployments/ssl/status \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"app.example.com"}'

openship deployment ssl status app.example.com
openship deployment ssl renew app.example.com

Errors you might see