Deployments

Last updated 04 November 2026

A deployment is one try to put a version of a service live: a build (for a GitHub service), then a start and a health check. If it works, it goes live and the one before it stops. If it fails, the one before it stays live.

The examples use API=https://dudbox.com/api/v1 and AUTH="Authorization: Bearer $DUDBOX_TOKEN".

The deployment object

{
  "id": 44,
  "service": "acme/shop",
  "status": "live",
  "done": true,
  "error": null,
  "trigger": "git",
  "created_at": "2026-11-04T09:30:00Z",
  "finished_at": "2026-11-04T09:31:12Z",
  "commit": { "sha": "9f2c…", "message": "Fix the cart", "branch": "main", "author": "rook", "repo": "acme/shop" },
  "rollback_of": null,
  "can_rollback": true
}

• status: queued, building and starting are in progress. live: it serves traffic now. failed: the build or the health check failed. superseded: it was live, then a newer one replaced it. cancelled: stopped before it went live.
• done: true when the status will not change any more. Wait for this.
• error: one line on why it failed. The build log has the rest.
• commit: null for a one-click app.
• can_rollback: its image is still kept, so a rollback to it needs no build.

GET /api/v1/services/{project}/{service}/deployments

The newest 20 deployments of a service, newest first: {"deployments": [Deployment, …]}.

POST /api/v1/services/{project}/{service}/redeploy

Starts the live version again, with the current env vars and no build. A one-click app pulls its image again. Use it after you change env vars.

curl -s -X POST $API/services/acme/shop/redeploy -H "$AUTH"

Answer: 201 with the new deployment. A service that was never built gets 400.

POST /api/v1/services/{project}/{service}/deploy

For a GitHub service: builds and deploys the newest commit of its branch now. A push does this by itself; use this when you do not want to wait or push.

Answer: 201 with the new deployment. A service without a repo gets 400.

POST /api/v1/services/{project}/{service}/rollback

Makes an older deployment live again, with no build. With no body, it goes to the deployment before the live one. With {"to": 41}, it goes to deployment 41. Only deployments with "can_rollback": true work.

curl -s -X POST $API/services/acme/shop/rollback -H "$AUTH" -H 'content-type: application/json' -d '{"to": 41}'

Answer: 201 with the new deployment (its rollback_of is 41).

GET /api/v1/deployments/{id}

One deployment. With ?wait=N (at most 300), the answer waits until the deployment is done or N seconds pass, then gives its status. This is the best way to wait for a deploy:

curl -s "$API/deployments/44?wait=300" -H "$AUTH"

If done is still false after the wait, call it again.

GET /api/v1/deployments/{id}/log

The build and start log, as text in JSON:

{ "deployment_id": 44, "log": "building with railpack…\n…", "offset": 18234, "done": true }

To get only new text, pass the last offset back: GET .../log?offset=18234. Secret env values are masked in the log.

GET /api/v1/deployments/{id}/events

The deployment live, as server-sent events, until it is done:

• deployment: the deployment object, at the start and on each status change.
• log: new log text, as a JSON string.
• end: the final status, as a JSON string. Then the stream closes.

curl -sN $API/deployments/44/events -H "$AUTH"

event: deployment
data: {"id":44,"service":"acme/shop","status":"building","done":false,…}

event: log
data: "installing packages\n"

event: end
data: "live"

?offset=N skips the first N characters of the log.

POST /api/v1/deployments/{id}/cancel

Stops a deployment that is still queued, building or starting. The live one stays.

Answer: 200 with the deployment (now cancelled). A deployment that is done gets 409.