Runbooks API Reference

Runbooks are DB-native, versioned remediation playbooks. This API manages catalog, versions, publish state.

Base URL: http://localhost:3003

Auth + Permissions

incidents:view for read/list.
policy:update for create/version/publish/archive.

GET /runbooks?status=published&actionType=restart-service

List runbooks by status and optional action type.

Query Parameters

Parameter	Type	Required	Description
`status`	`draft \| published \| archived`	No	Filter lifecycle status
`actionType`	remediation action type	No	Filter action-tagged runbooks

Response

[
  {
    "id": "r0000000-0000-4000-8000-000000000001",
    "slug": "restart-payments",
    "title": "Restart payments service",
    "latestVersion": "1.2.0",
    "status": "published",
    "actionTags": ["restart-service"]
  }
]

POST /runbooks

Create runbook draft with initial version 1.0.0.

Body

{
  "slug": "restart-payments",
  "title": "Restart payments service",
  "ownerTeam": "platform",
  "contentMd": "# Steps\n1. Validate alarm\n2. Restart deployment",
  "createdBy": "alice",
  "changeSummary": "initial draft",
  "actionTags": ["restart-service"]
}

POST /runbooks/:id/versions

Append runbook version.

Body

{
  "version": "1.1.0",
  "contentMd": "# Updated steps",
  "createdBy": "alice",
  "changeSummary": "added fallback checks"
}

POST /runbooks/:id/publish

Promote runbook status to published.

Response

{ "published": true }

POST /runbooks/:id/archive

Promote runbook status to archived. Archived runbooks remain readable in catalog/history, but should not be presented as incident-ready playbooks.

Response

{ "archived": true }