Playbooks API: build, execute, and manage runbooks

Playbooks in Scrubbe are versioned, executable runbooks that codify your team’s incident response procedures. You can create and publish playbooks through the API, match a playbook to a live incident context, and trigger executions that guide responders through each step — completing or skipping steps individually, recording ad-hoc actions, and cancelling when needed. Ezra AI can also suggest response actions based on real-time incident context, and the patterns endpoint surfaces lessons from historical executions.

All endpoints require Authorization: Bearer <token>. Only published playbooks are eligible for matching and execution. Use POST /:id/publish to promote a draft.

Base path: https://your-api-domain.com/api/v1/playbooks

Create a playbook

Creates a new playbook in DRAFT status. Publish it with POST /:id/publish when it is ready for use in incidents. POST https://your-api-domain.com/api/v1/playbooks

string

required

Short title for the playbook (e.g. "Database failover response").

string

Overview of when this playbook should be used.

object[]

required

Ordered list of response steps.

Show step properties

string

required

Step title.

string

Detailed instructions for the responder.

boolean

default:"false"

Whether this step can be skipped.

object

Conditions used during automatic matching — service area, severity, environment, and similar fields.

curl -X POST https://your-api-domain.com/api/v1/playbooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database failover response",
    "description": "Steps to handle an unplanned database primary failover.",
    "steps": [
      { "title": "Verify failover status", "instructions": "Check replication lag and confirm replica is promoted." },
      { "title": "Update DNS / connection strings", "instructions": "Point services to new primary endpoint." },
      { "title": "Confirm service recovery", "instructions": "Validate error rates have returned to baseline." }
    ],
    "triggerConditions": { "serviceArea": "database", "priority": "CRITICAL" }
  }'

import requests

resp = requests.post(
    'https://your-api-domain.com/api/v1/playbooks',
    headers={'Authorization': 'Bearer <token>'},
    json={
        'title': 'Database failover response',
        'description': 'Steps to handle an unplanned database primary failover.',
        'steps': [
            {'title': 'Verify failover status', 'instructions': 'Check replication lag and confirm replica is promoted.'},
            {'title': 'Update DNS / connection strings', 'instructions': 'Point services to new primary endpoint.'},
            {'title': 'Confirm service recovery', 'instructions': 'Validate error rates have returned to baseline.'},
        ],
        'triggerConditions': {'serviceArea': 'database', 'priority': 'CRITICAL'},
    },
)
print(resp.json())

string

required

Unique playbook identifier.

string

required

Initial status — always DRAFT.

string

required

ISO 8601 creation timestamp.

List playbooks

Returns a paginated list of playbooks ordered by creation date descending. Filter by status to view only published playbooks available for execution. GET https://your-api-domain.com/api/v1/playbooks

number

default:"1"

Page number.

number

default:"20"

Items per page (max 100).

string

Filter by status: DRAFT or PUBLISHED.

cURL

curl "https://your-api-domain.com/api/v1/playbooks?status=PUBLISHED" \
  -H "Authorization: Bearer <token>"

Get playbook stats

Returns aggregate statistics across all playbooks — total executions, average completion time, step skip rates, and most-executed playbooks. GET https://your-api-domain.com/api/v1/playbooks/stats

cURL

curl https://your-api-domain.com/api/v1/playbooks/stats \
  -H "Authorization: Bearer <token>"

number

Total playbook count in the workspace.

number

Total number of executions across all playbooks.

number

Average time to complete an execution in minutes.

number

Proportion of optional steps skipped across all executions, from 0 to 1.

Get a playbook

Fetch a single playbook by its ID, including its full step list and trigger conditions. GET https://your-api-domain.com/api/v1/playbooks/:id

string

required

The playbook ID.

cURL

curl https://your-api-domain.com/api/v1/playbooks/PB-0012 \
  -H "Authorization: Bearer <token>"

Update a playbook

Update an existing playbook. Only the fields you provide are modified. Updating a published playbook creates a new draft version; use POST /:id/publish to promote it. PUT https://your-api-domain.com/api/v1/playbooks/:id

string

required

The playbook ID.

Accepts the same body fields as POST /.

Publish a playbook

Promote a draft playbook to PUBLISHED status, making it eligible for matching and execution. POST https://your-api-domain.com/api/v1/playbooks/:id/publish

string

required

The playbook ID to publish.

cURL

curl -X POST https://your-api-domain.com/api/v1/playbooks/PB-0012/publish \
  -H "Authorization: Bearer <token>"

Delete a playbook

Permanently delete a playbook and all its associated execution history. DELETE https://your-api-domain.com/api/v1/playbooks/:id

string

required

The playbook ID to delete.

Deletion is permanent and removes all execution history. Consider keeping published playbooks and creating updated draft versions instead.

Match a playbook to an incident

Find the best-matching published playbook for a given incident context. Scrubbe scores all published playbooks against the provided context and returns the top match. POST https://your-api-domain.com/api/v1/playbooks/match

string

ID of the active incident. Scrubbe reads its context automatically.

string

Service area to match against when not providing an incident ID.

string

Incident priority: LOW, MEDIUM, HIGH, or CRITICAL.

string

Target environment (e.g. "production", "staging").

cURL

curl -X POST https://your-api-domain.com/api/v1/playbooks/match \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "incidentId": "INC-20260522-0041" }'

string

required

ID of the best-matched playbook.

string

required

Playbook title.

number

Confidence score for the match, from 0 to 1.

Execute a playbook

Start a new execution of a published playbook. Returns an execution ID that you use to track and drive progress through each step. POST https://your-api-domain.com/api/v1/playbooks/:id/execute

string

required

The playbook ID to execute.

string

Link this execution to an active incident.

string

Email address of the engineer leading the execution.

curl -X POST https://your-api-domain.com/api/v1/playbooks/PB-0012/execute \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "incidentId": "INC-20260522-0041",
    "assignedToEmail": "oncall@example.com"
  }'

const resp = await fetch(
  'https://your-api-domain.com/api/v1/playbooks/PB-0012/execute',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      incidentId: 'INC-20260522-0041',
      assignedToEmail: 'oncall@example.com',
    }),
  }
);
const { data } = await resp.json();

string

required

Unique identifier for this execution.

string

required

Execution status — IN_PROGRESS on creation.

List executions

Returns a paginated list of all playbook executions in the workspace. GET https://your-api-domain.com/api/v1/playbooks/executions/list

number

default:"1"

Page number.

number

default:"20"

Items per page (max 100).

string

Filter by execution status: IN_PROGRESS, COMPLETED, or CANCELLED.

cURL

curl "https://your-api-domain.com/api/v1/playbooks/executions/list?status=IN_PROGRESS" \
  -H "Authorization: Bearer <token>"

Get an execution

Fetch a single execution by its ID, including current step progress and per-step status. GET https://your-api-domain.com/api/v1/playbooks/executions/:executionId

string

required

The execution ID.

cURL

curl https://your-api-domain.com/api/v1/playbooks/executions/EXEC-20260522-0005 \
  -H "Authorization: Bearer <token>"

string

required

Execution identifier.

string

required

ID of the playbook being executed.

string

Linked incident ID, if any.

string

required

Execution status: IN_PROGRESS, COMPLETED, or CANCELLED.

number

Zero-based index of the step currently in progress.

object[]

Per-step state.

Show step object

number

Zero-based step position.

string

Step title.

string

PENDING, IN_PROGRESS, COMPLETED, or SKIPPED.

string

Responder notes added on completion.

string

required

ISO 8601 timestamp when execution began.

Complete a step

Mark a step in an active execution as completed and advance to the next step. POST https://your-api-domain.com/api/v1/playbooks/executions/:executionId/steps/:stepIndex/complete

string

required

The execution ID.

number

required

Zero-based index of the step to complete.

string

Optional notes from the responder about this step.

cURL

curl -X POST \
  "https://your-api-domain.com/api/v1/playbooks/executions/EXEC-20260522-0005/steps/1/complete" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "DNS updated and propagated" }'

Skip a step

Skip an optional step in an active execution. Only steps defined with "optional": true can be skipped. POST https://your-api-domain.com/api/v1/playbooks/executions/:executionId/steps/:stepIndex/skip

string

required

The execution ID.

number

required

Zero-based index of the step to skip.

string

Reason for skipping the step.

Skipping a required step returns a 400 error. Mark the step as optional in the playbook definition to allow skipping.

cURL

curl -X POST \
  "https://your-api-domain.com/api/v1/playbooks/executions/EXEC-20260522-0005/steps/2/skip" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Not applicable for this environment" }'

Record an ad-hoc action

Record an unscripted action taken during an execution — useful for capturing steps not covered by the playbook or for audit purposes. POST https://your-api-domain.com/api/v1/playbooks/executions/:executionId/action

string

required

The execution ID.

string

required

Description of the action taken.

cURL

curl -X POST \
  "https://your-api-domain.com/api/v1/playbooks/executions/EXEC-20260522-0005/action" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Rolled back deployment svc-payments@1.4.2 to 1.4.1" }'

Complete an execution

Mark the entire execution as COMPLETED once all required steps have been finished. POST https://your-api-domain.com/api/v1/playbooks/executions/:executionId/complete

string

required

The execution ID.

cURL

curl -X POST \
  "https://your-api-domain.com/api/v1/playbooks/executions/EXEC-20260522-0005/complete" \
  -H "Authorization: Bearer <token>"

Cancel an execution

Cancel an active execution. Cancelled executions are retained for audit purposes and excluded from completion rate statistics. POST https://your-api-domain.com/api/v1/playbooks/executions/:executionId/cancel

string

required

The execution ID.

string

Reason for cancelling the execution.

cURL

curl -X POST \
  "https://your-api-domain.com/api/v1/playbooks/executions/EXEC-20260522-0005/cancel" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Incident mitigated before playbook completion" }'

AI: suggest response actions

Ask Ezra AI to suggest ad-hoc response actions based on an incident context. Returns an ordered list of recommendations that responders can act on immediately or log via POST /executions/:executionId/action. POST https://your-api-domain.com/api/v1/playbooks/suggest

string

required

ID of the active incident to generate suggestions for.

curl -X POST https://your-api-domain.com/api/v1/playbooks/suggest \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "incidentId": "INC-20260522-0041" }'

const resp = await fetch('https://your-api-domain.com/api/v1/playbooks/suggest', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ incidentId: 'INC-20260522-0041' }),
});
const { data } = await resp.json();

string[]

required

Ordered list of AI-recommended response actions.

number

Overall confidence score for the suggestion set, from 0 to 1.

Get execution patterns

Returns patterns detected across playbook execution history — steps most frequently skipped, executions that correlated with faster resolution, and playbooks with the highest completion rates. GET https://your-api-domain.com/api/v1/playbooks/patterns

cURL

curl https://your-api-domain.com/api/v1/playbooks/patterns \
  -H "Authorization: Bearer <token>"

object[]

Array of detected execution patterns.

Show pattern object

string

required

Unique pattern identifier.

string

required

Description of the execution pattern.

string

Playbook associated with this pattern, if any.

number

required

Number of executions matching this pattern.

string

Ezra’s recommendation based on the pattern.

Overview

Incidents & Tickets

Intelligence

Operations

Platform

Playbooks API: build, execute, and manage runbooks

Create a playbook

List playbooks

Get playbook stats

Get a playbook

Update a playbook

Publish a playbook

Delete a playbook

Match a playbook to an incident

Execute a playbook

List executions

Get an execution

Complete a step

Skip a step

Record an ad-hoc action

Complete an execution

Cancel an execution

AI: suggest response actions

Get execution patterns

​Create a playbook

​List playbooks

​Get playbook stats

​Get a playbook

​Update a playbook

​Publish a playbook

​Delete a playbook

​Match a playbook to an incident

​Execute a playbook

​List executions

​Get an execution

​Complete a step

​Skip a step

​Record an ad-hoc action

​Complete an execution

​Cancel an execution

​AI: suggest response actions

​Get execution patterns

Create a playbook

List playbooks

Get playbook stats

Get a playbook

Update a playbook

Publish a playbook

Delete a playbook

Match a playbook to an incident

Execute a playbook

List executions

Get an execution

Complete a step

Skip a step

Record an ad-hoc action

Complete an execution

Cancel an execution

AI: suggest response actions

Get execution patterns