Update a deploy

PATCH /v1/deploys/{deploy_id}
Moves a deploy that Record a deploy opened, as b3os apply runs it: building when it starts writing, applying at the cutover, then live, failed or cancelled, with what it did per item. Only the credential that opened it can change it, and only forward (deploy_not_updatable otherwise); the GitHub App's deploys change only on B3OS. A request without status keeps the status and records that the deploy is still moving; b3os apply sends one at least every 5 minutes, and a deploy left queued, building or applying with no update for 20 minutes is failed by the 15-minute sweep, which undoes nothing (the CLI undoes its own work; what it left ends within its lease). Going live makes the deploy that was live in the same project superseded, and stops B3OS renewing that deploy's services, since they were replaced; the answer's reason then says so. A run that went wrong after its cutover goes live with error set.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token)

Path Parameters

deploy_id string required path
Pattern ^dep_[0-9a-hjkmnp-tv-z]{26}$
Example: "dep_01m6a2zq8x9hkqd3n7c5b4v2tw"

Request Body required

application/json
status string
Values building applying live failed cancelled
step string | null
Max length 200
plan object
The plan as b3os apply printed it, its counts and its findings at their line in b3os.yaml.
text string REQUIRED
Max length 200000
summary object REQUIRED
Plan items per action.
create integer
update integer
ok integer
gap integer
problem integer
unchecked integer
remove integer
findings object[]
Max items 500
items object[]
Max items 1000
manifest_sha string | null
Pattern ^[0-9a-f]{12,64}$
error string | null
Why it failed, in words for people (failed); with live, what went wrong after the cutover of a deploy that serves anyway.
Max length 2000
reason string | null
Why it was cancelled (cancelled).
Max length 1000

Responses

200 The deploy.
application/json
id string REQUIRED
object string REQUIRED
Values deploy
app string REQUIRED
An application's name, the name in its b3os.yaml.
env string REQUIRED
project_id string REQUIRED
status string REQUIRED
queued (waiting its turn), building (plan, routines, builds and new service generations, all undone on a failure), applying (the cutover), live (what the application runs now, also when something went wrong after its cutover: error says what), superseded (was live; a newer deploy went live), failed, cancelled (stopped before it started: a newer commit, an unlinked repository, a removed installation; or stopped part-way and undone: a cancelled workflow run, Ctrl-C, a newer deploy) or skipped (nothing the manifest reads changed, auto-deploy is paused, or the branch had already moved past the pushed commit).
Values queued building applying live superseded failed cancelled skipped
source string REQUIRED
What ran the deploy: github_app (a push to the linked branch, or Deploy in the dashboard), redeploy and rollback (the dashboard's, through the GitHub App), or b3os apply, which records its own deploys: cli from a machine, github_actions from a workflow.
Values cli github_actions github_app redeploy rollback
requested_by string | null REQUIRED
The GitHub login that pushed (or that ran the workflow, for github_actions), or the user or key that asked for a redeploy or rollback, or that ran b3os apply (cli).
commit object | null REQUIRED
sha string REQUIRED
message string | null REQUIRED
branch string | null REQUIRED
dirty boolean REQUIRED
The tree held uncommitted changes, which deployed with it (b3os apply from a machine).
repository object | null REQUIRED
id integer | null REQUIRED
GitHub's id; null when b3os apply named the repository without it.
full_name string REQUIRED
installation_id integer | null REQUIRED
manifest_path string REQUIRED
manifest_sha string | null REQUIRED
previous_id string | null REQUIRED
The deploy that was live before this one went live.
rollback_of string | null REQUIRED
The deploy a rollback ran again: the dashboard's (source: rollback), or b3os app rollback's (source: cli or github_actions).
recreated object[] | null
A deploy b3os apply --keepalive recorded because it recreated services: each one and why, with its lost process's last lines. Null for any other deploy, and absent from edges before 2026-11-11.
Array of:
item string REQUIRED
service/<name>.
cause string REQUIRED
Values process crash lease probe stopped
reason string REQUIRED
In words, with the time in UTC (process 466 killed by TERM at 01:15:37 UTC, the lease ended at 20:24:07 UTC).
lines string[] REQUIRED
plan_summary object | null REQUIRED
Plan items per action.
create integer
update integer
ok integer
gap integer
problem integer
unchecked integer
remove integer
plan object | null
Get a deploy only. The plan as b3os apply --dry-run printed it, with its findings.
text string
summary object
Plan items per action.
create integer
update integer
ok integer
gap integer
problem integer
unchecked integer
remove integer
findings object[]
items object[]
Get a deploy only. Per item, what the deploy did and the ids it made, and since 2026-11-11 when each step began and ended (started_at, ended_at; a new generation also probe and cutover, each with both times). Older records have no times.
output object[]
Get a deploy only. What the processes of a deploy B3OS ran printed, per step (a build's apt step when build.apt lists packages, a build's install, a generation's prepare), in the order the steps started: the last 400 lines or 64 KiB of each, whichever is smaller, with credentials in URLs and paths redacted. Written as the output arrives, about every 5 seconds while a step runs, so a deploy that is building shows its install as it goes. Empty for a deploy b3os apply recorded: it prints the output where it runs.
Array of:
item string REQUIRED
The item the step belongs to (build/agent for an apt step or an install, service/agent for a prepare).
step string REQUIRED
apt is the build's apt-get install of build.apt, run as root before install.
Values install prepare apt
status string REQUIRED
running while the process runs; a step the deploy stopped before it ended is failed.
Values running succeeded failed
lines string[] REQUIRED
The newest lines, oldest first, without their newline.
dropped integer REQUIRED
Earlier lines that are no longer kept.
started_at string (date-time) REQUIRED
ended_at string (date-time) | null REQUIRED
step string | null
Where the deploy is, in the deployer's words (build/agent install-wait (2 min), service/agent ready), as it last reported; null before it starts.
run_url string | null
The GitHub Actions run that deployed it (source: github_actions).
checks object REQUIRED
The check runs on the commit (GitHub ids).
deploy integer | null REQUIRED
plan integer | null REQUIRED
error string | null REQUIRED
Why it failed. On a live deploy: what went wrong after its cutover (a retire, a service that stopped, a run cut short); its new generations serve anyway, and B3OS keeps them alive.
reason string | null REQUIRED
Why it was cancelled or skipped. On a live deploy b3os apply recorded: that it replaced a deploy B3OS kept alive, so nothing but b3os apply renews the application now.
github_error string | null REQUIRED
The last check run or comment GitHub refused (the deploy went on without it).
attempts integer REQUIRED
created_at string (date-time) REQUIRED
updated_at string (date-time) REQUIRED
started_at string (date-time) | null REQUIRED
live_at string (date-time) | null REQUIRED
finished_at string (date-time) | null REQUIRED
400 The request failed validation (invalid_request, invalid_url).
401 Missing, malformed, expired or revoked credentials (unauthorized).
403 Authenticated but not allowed (forbidden, egress_denied).
404 No such deploy in your organization (deploy_not_found).
409 The deploy cannot change this way (deploy_not_updatable).
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
429 A rate, concurrency or quota limit applies (rate_limited, concurrency_limited, quota_exceeded).
500 Something failed inside B3OS (internal). Retry with backoff.
503 The node or the product is not available right now (node_unavailable, product_unavailable, capacity_unavailable). 
curl -X PATCH 'https://beta-api.b3os.org/v1/deploys/dep_01m6a2zq8x9hkqd3n7c5b4v2tw' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "status": "live",  "items": [    {      "item": "service/agent",      "did": "started"    }  ]}'
const response = await fetch('https://beta-api.b3os.org/v1/deploys/dep_01m6a2zq8x9hkqd3n7c5b4v2tw', {  method: 'PATCH',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "status": "live",    "items": [      {        "item": "service/agent",        "did": "started"      }    ]  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.patch('https://beta-api.b3os.org/v1/deploys/dep_01m6a2zq8x9hkqd3n7c5b4v2tw', headers=headers, json={  "status": "live",  "items": [    {      "item": "service/agent",      "did": "started"    }  ]})print(response.json())
200 Response 
{  "id": "dep_01m6a2zq8x9hkqd3n7c5b4v2tw",  "object": "deploy",  "app": "research-agent",  "env": "production",  "project_id": "prj_01m5t3pf8heewxt65ej3dm577y",  "status": "live",  "source": "github_actions",  "requested_by": "dana",  "commit": {    "sha": "3f2c1b0a9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a",    "message": "Update the harness",    "branch": "main",    "dirty": false  },  "repository": {    "id": 812345678,    "full_name": "acme/research-agent"  },  "installation_id": null,  "manifest_path": "b3os.yaml",  "manifest_sha": "0123456789ab",  "previous_id": null,  "rollback_of": null,  "plan_summary": {    "create": 1,    "update": 0,    "ok": 1,    "gap": 0,    "problem": 0,    "unchecked": 0,    "remove": 0  },  "plan": {    "text": "  + service agent  new generation",    "summary": {      "create": 1,      "update": 0,      "ok": 1,      "gap": 0,      "problem": 0,      "unchecked": 0,      "remove": 0    },    "findings": []  },  "items": [    {      "item": "service/agent",      "did": "started"    }  ],  "step": null,  "run_url": "https://github.com/acme/research-agent/actions/runs/18492771204",  "checks": {    "deploy": null,    "plan": null  },  "error": null,  "reason": null,  "github_error": null,  "attempts": 0,  "created_at": "2026-11-07T09:10:00.000Z",  "updated_at": "2026-11-07T09:12:00.000Z",  "started_at": "2026-11-07T09:10:05.000Z",  "live_at": "2026-11-07T09:12:00.000Z",  "finished_at": "2026-11-07T09:12:00.000Z"}
Previous Get a deploy
Next Redeploy
Ask a question... ⌘I