Run playbook

This guide explains how to execute and monitor playbooks through the S4E REST API. Playbooks orchestrate multiple actions into repeatable, automated security workflows.

What Are Playbooks?

A playbook is an ordered sequence of actions that S4E executes as a single workflow. While individual actions handle discrete tasks (send a notification, run a script), playbooks chain them together with control flow, conditional branching, and shared context. Common examples include:

Incident triage -- Enrich a finding, assign severity, notify the on-call team, and open a ticket.
Automated patching -- Verify the vulnerability, apply a patch in dry-run mode, validate, then apply for real.
Compliance check -- Run a scan, compare results against a policy baseline, generate a report, and email stakeholders.

Note

Playbooks are created and edited through the S4E dashboard or the POST /api/playbooks endpoint. This guide focuses on executing an existing playbook and monitoring its progress.

Endpoint

POST https://api.s4e.io/api/playbooks/{playbook_id}/run

Path Parameters

Parameter	Type	Description
playbook_id	string	UUID of the playbook to execute.

Required Headers

Header	Value	Description
Authorization	`Bearer <token>`	Your API authentication token.
Content-Type	`application/json`	Request body format.

Request Payload

Field	Type	Required	Description
target_asset_id	string	Yes	UUID of the asset the playbook will operate on.
parameters	object	No	Key-value pairs passed to the playbook as runtime variables.
dry_run	boolean	No	When `true`, the playbook simulates all steps without side effects. Default `false`.

Parameters Object

The parameters object passes runtime configuration to individual actions within the playbook. Available keys depend on the playbook definition. Consult the playbook detail endpoint (GET /api/playbooks/{playbook_id}) for the schema of accepted parameters.

{
  "target_asset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parameters": {
    "notify_channel": "#incident-response",
    "patch_version": "2.4.1",
    "rollback_enabled": true
  },
  "dry_run": false
}

Tip

Always run a playbook with dry_run: true first, especially in production environments. The dry-run execution validates every step and reports what would happen without making any changes.

Response Format

A successful request returns 202 Accepted:

{
  "execution_id": "exec-aabb1122-3344-5566-7788-99aabbccddee",
  "playbook_id": "pb-11223344-5566-7788-99aa-bbccddeeff00",
  "status": "pending",
  "dry_run": false,
  "created_at": "2026-04-28T11:00:00Z",
  "steps": [
    {"index": 0, "action_id": "act-001", "name": "Enrich finding",    "status": "pending"},
    {"index": 1, "action_id": "act-002", "name": "Notify Slack",      "status": "pending"},
    {"index": 2, "action_id": "act-003", "name": "Apply remediation", "status": "pending"},
    {"index": 3, "action_id": "act-004", "name": "Verify fix",        "status": "pending"}
  ]
}

Field	Type	Description
execution_id	string	Unique identifier for this execution run.
playbook_id	string	The playbook that was executed.
status	string	Overall execution status.
dry_run	boolean	Whether this is a simulation.
created_at	string	ISO 8601 timestamp of execution start.
steps	array	Ordered list of steps with individual statuses.

Monitoring Execution

Poll the execution status endpoint to track progress:

GET https://api.s4e.io/api/playbooks/executions/{execution_id}

Execution States

The overall execution and each individual step transition through the following states:

State	Description
pending	The execution or step is queued and has not started yet.
running	The execution or step is actively in progress.
completed	The execution or step finished successfully.
failed	The execution or step encountered an error and could not continue.
skipped	The step was skipped because a preceding condition was not met.
cancelled	The execution was explicitly cancelled by a user or policy.

Status Response Example

{
  "execution_id": "exec-aabb1122-3344-5566-7788-99aabbccddee",
  "playbook_id": "pb-11223344-5566-7788-99aa-bbccddeeff00",
  "status": "running",
  "started_at": "2026-04-28T11:00:05Z",
  "steps": [
    {"index": 0, "name": "Enrich finding",    "status": "completed", "duration_ms": 1200},
    {"index": 1, "name": "Notify Slack",      "status": "completed", "duration_ms": 340},
    {"index": 2, "name": "Apply remediation", "status": "running",   "duration_ms": null},
    {"index": 3, "name": "Verify fix",        "status": "pending",   "duration_ms": null}
  ]
}

Warning

If a step enters the failed state, subsequent steps may be skipped depending on the playbook's error-handling strategy. Check the steps array for individual step statuses to understand exactly where a failure occurred.

Cancelling an Execution

To cancel a running execution:

POST https://api.s4e.io/api/playbooks/executions/{execution_id}/cancel

This returns 200 OK and sets the execution status to cancelled. Steps that have already completed are not rolled back.

Error Handling

HTTP Code	Meaning	Typical Cause
400	Bad Request	Invalid payload or missing required fields.
401	Unauthorized	Missing or expired Bearer token.
403	Forbidden	Token lacks `playbook:execute` permission.
404	Not Found	Playbook or asset not found.
409	Conflict	This playbook is already running for the asset.
422	Unprocessable Entity	Parameter validation failed against the playbook schema.

Example: Run an Incident Triage Playbook

# Execute the playbook
curl -X POST "https://api.s4e.io/api/playbooks/pb-11223344-5566-7788-99aa-bbccddeeff00/run" \
  -H "Authorization: Bearer $S4E_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_asset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parameters": {
      "notify_channel": "#incident-response",
      "auto_assign": true
    },
    "dry_run": true
  }'

# Monitor execution
curl -s "https://api.s4e.io/api/playbooks/executions/exec-aabb1122-3344-5566-7788-99aabbccddee" \
  -H "Authorization: Bearer $S4E_API_TOKEN" | python3 -m json.tool

Tip

After a dry-run succeeds, re-run the same request with "dry_run": false to apply the playbook for real. Comparing the dry-run output with the live execution output is a reliable way to verify expected behaviour.