Playbooks

The Playbooks API lets you create, manage, and execute automated security workflows that orchestrate multiple actions in sequence.

List Playbooks

GET /api/playbooks

Query Parameters

Parameter Type Default Description
search string Search in playbook name and description.
tag string Filter by tag.
page integer 1 Page number.
per_page integer 20 Results per page (max 100).

Example

curl -X GET "https://api.s4e.io/api/playbooks?tag=incident-response" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "pb-critical-vuln-response",
      "name": "Critical Vulnerability Response",
      "version": "1.2.0",
      "description": "Automated triage and response for critical vulnerabilities.",
      "trigger": {
        "event": "finding.new",
        "conditions": {"severity": "critical"}
      },
      "step_count": 5,
      "tags": ["security", "automated", "incident-response"],
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-04-15T14:00:00Z"
    }
  ],
  "meta": {
    "total": 8,
    "page": 1,
    "per_page": 20
  }
}

Create Playbook

POST /api/playbooks

Request Body

Field Type Required Description
name string Yes Playbook name.
version string Yes Semantic version.
description string No Purpose and scope.
trigger object Yes Trigger event and conditions.
steps array Yes Ordered list of workflow steps.
on_failure string No Global failure strategy: abort, continue.
timeout_minutes integer No Maximum execution time.
tags array No Labels for filtering.

Example

curl -X POST "https://api.s4e.io/api/playbooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Critical Finding Alert",
    "version": "1.0.0",
    "description": "Notify team and create ticket for critical findings.",
    "trigger": {
      "event": "finding.new",
      "conditions": {"severity": "critical"}
    },
    "steps": [
      {
        "id": "notify",
        "name": "Notify Security Team",
        "type": "action",
        "action_ref": "act-slack-notify",
        "parameters": {
          "channel": "#security-alerts",
          "message": "Critical finding: {{ finding.title }}"
        },
        "on_success": "create-ticket"
      },
      {
        "id": "create-ticket",
        "name": "Create JIRA Ticket",
        "type": "action",
        "action_ref": "act-jira-create",
        "parameters": {
          "project": "SEC",
          "summary": "{{ finding.title }}",
          "priority": "Critical"
        }
      }
    ],
    "on_failure": "abort",
    "timeout_minutes": 30,
    "tags": ["incident-response"]
  }'

Response (201 Created)

{
  "data": {
    "id": "pb-critical-finding-alert",
    "name": "Critical Finding Alert",
    "version": "1.0.0",
    "step_count": 2,
    "created_at": "2026-04-28T12:00:00Z"
  }
}

Get Playbook Details

GET /api/playbooks/{id}

Returns the full playbook definition including all steps and configuration.

curl -X GET "https://api.s4e.io/api/playbooks/pb-critical-vuln-response" \
  -H "Authorization: Bearer YOUR_API_KEY"

Run Playbook

POST /api/playbooks/{id}/run

Request Body

Field Type Required Description
target_asset_id string No Asset to run the playbook against.
parameters object No Override default parameters.
dry_run boolean No Simulate without executing (default: false).

Example

curl -X POST "https://api.s4e.io/api/playbooks/pb-critical-vuln-response/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_asset_id": "a-1001",
    "parameters": {
      "notification_channel": "#incidents"
    },
    "dry_run": false
  }'

Response

{
  "data": {
    "execution_id": "pexec-7721",
    "playbook_id": "pb-critical-vuln-response",
    "status": "running",
    "started_at": "2026-04-28T12:00:00Z"
  }
}

Get Execution Status

GET /api/playbooks/executions/{exec_id}

curl -X GET "https://api.s4e.io/api/playbooks/executions/pexec-7721" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "execution_id": "pexec-7721",
    "playbook_id": "pb-critical-vuln-response",
    "playbook_name": "Critical Vulnerability Response",
    "status": "completed",
    "current_step": null,
    "steps_completed": 5,
    "steps_total": 5,
    "started_at": "2026-04-28T12:00:00Z",
    "completed_at": "2026-04-28T12:02:15Z",
    "duration_seconds": 135
  }
}

Get Step Details

GET /api/playbooks/executions/{exec_id}/steps

Returns the status and output of each step in the execution:

curl -X GET "https://api.s4e.io/api/playbooks/executions/pexec-7721/steps" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "step_id": "notify",
      "step_name": "Notify Security Team",
      "type": "action",
      "status": "completed",
      "output": {"message_ts": "1714305660.001234"},
      "started_at": "2026-04-28T12:00:01Z",
      "completed_at": "2026-04-28T12:00:03Z"
    },
    {
      "step_id": "create-ticket",
      "step_name": "Create JIRA Ticket",
      "type": "action",
      "status": "completed",
      "output": {"issue_key": "SEC-1234"},
      "started_at": "2026-04-28T12:00:03Z",
      "completed_at": "2026-04-28T12:00:08Z"
    }
  ]
}

Execution States

State Description
pending Execution is queued and waiting to start.
running Execution is actively processing steps.
paused Execution is waiting for approval or delay.
completed All steps finished successfully.
failed A step failed and on_failure is set to abort.
cancelled Execution was manually cancelled.

Import / Export

Export to CACAO

curl -X GET "https://api.s4e.io/api/playbooks/pb-critical-vuln-response/export?format=cacao_v2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o playbook.json

Import from CACAO

curl -X POST "https://api.s4e.io/api/playbooks/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @cacao-playbook.json

Tip

Use "dry_run": true in the import request to preview conversion without creating the playbook.

Next Steps