API reference

Base URL: https://deployment-playbook.com (or your own host). All requests and responses are JSON.

Authentication: workspace API tokens

• An Admin creates tokens on Connections & webhooks (/w/<workspace>/connections). The token (dpk_…) is shown once; only a SHA-256 hash is stored. Tokens can be revoked at any time; the page shows when each was last used.
• Send it as Authorization: Bearer <token>.
• A token belongs to one workspace and can only see that workspace's templates and plans.
• Plans created with a token are created on behalf of the Admin who created the token: that person must still be a member with a role that may create plans (Approver, Template manager or Admin), otherwise the API returns 403. With four-eyes on, that person counts as the proposer, so other people must approve.
• Tokens can create and read; they can never approve anything.

POST /api/plans

Create a plan from a template (status PROPOSED). Idempotent per workspace + repository + ref.

Field	Type	Required	Description
templateId	string	yes*	Template ID (Templates → template → Copy). Recommended: stable when renamed.
template	string	*	Backwards compatible: template id or exact template name. Used only when templateId is absent.
name	string	no	Plan name. Default Release <ref> (or Release <date time> without ref). Max 200.
environment	string	no	Default production. Max 100.
ref	string	no	Tag or branch, e.g. v1.4.0. Max 255.
repository	string	no	e.g. acme/shop. Max 255. With ref it makes the call idempotent.
commitSha	string	no	Commit SHA (shown on the plan page).
runUrl	string	no	http(s) link to the CI run (shown on the plan page).
fourEyes	boolean	no	Plan-wide four-eyes. Default false; per-step four-eyes from the template still applies.

* one of templateId or template is required.

curl -sS -X POST https://deployment-playbook.com/api/plans \
  -H "Authorization: Bearer $PLAYBOOK_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"templateId":"cmabc123template","ref":"v1.4.0","repository":"acme/shop","commitSha":"3f2c1ab","runUrl":"https://github.com/acme/shop/actions/runs/1","environment":"production"}'

Response 201 Created (new plan) or 200 OK (a plan for this repository + ref already existed):

{
  "id": "cmplan123",
  "name": "Release v1.4.0",
  "status": "PROPOSED",
  "planUrl": "https://deployment-playbook.com/w/acme/plans/cmplan123",
  "gateUrl": "https://deployment-playbook.com/api/gate/cmplan123",
  "created": true
}

Errors return {"error": "<message>"}:

Status	When
400	Body is not JSON or a field is invalid (e.g. runUrl is not http(s)); template archived or without steps.
401	Missing, invalid or revoked token.
403	Token creator is no longer allowed to create plans, or the workspace's plan limit is reached.
404	Template not found in this workspace.
500	Unexpected error (no internals are returned).

GET /api/gate/:planId

GET /api/gate/<planId>?phase=before|during|after[&step=<planStepId>], header Authorization: Bearer <token>.

Param	Description
phase	Phase whose work may start. Default during. before: the plan is approved. during: all Before steps resolved. after: all Before + During steps resolved.
step	Optional plan step id: additionally all earlier steps in the same phase must be resolved (the phase is taken from the step).

"Resolved" = approved, or skipped when optional. The plan must be approved (IN_PROGRESS) or DONE, and no step may be rejected.

Response (always HTTP 200 for a valid token and plan):

{
  "allow": false,
  "reason": "2 steps in \"Before deployment\" still open",
  "gatePhase": "DURING",
  "planStatus": "in_progress",
  "currentPhase": "BEFORE",
  "steps": { "approved": 6, "skipped": 0, "total": 19 },
  "planUrl": "https://deployment-playbook.com/w/acme/plans/cmplan123"
}

Field	Description
allow	true when work in gatePhase may start.
reason	Human-readable explanation.
gatePhase	The phase that was evaluated (BEFORE, DURING, AFTER).
planStatus	waiting_for_approval, in_progress, rejected, done, rolled_back. Use done to detect that the whole plan (incl. After) is complete.
currentPhase	First phase with open steps, or null when everything is resolved.
steps	Counts of approved, skipped and total steps.
planUrl	Link to the plan.

The gate fails closed: 401 (bad token), 404 (unknown plan or another workspace's plan) and 500 all return {"allow": false, "reason": "…"}. Treat anything other than 200 + allow: true as "wait".

curl -sS -H "Authorization: Bearer $PLAYBOOK_API_TOKEN" \
  "https://deployment-playbook.com/api/gate/cmplan123?phase=after" | jq '{allow, planStatus, reason}'

MCP endpoint

POST /api/mcp (Streamable HTTP, same Bearer token). See Use with AI.

Rate of polling

Poll every 10–30 seconds. Each call is cheap, but there is no reason to poll faster than people approve.