Private betaThe Capx developer platform is available to private beta participants. Join the waitlist for access.

API Reference

Playbooks API

Playbooks are reusable, declarative workflows that define what your agents do and how they do it. They are the primary unit of work in Capx. Use these endpoints to create playbooks, trigger runs, and inspect execution history.

Create a Playbook

POST/companies/:id/playbooksCreate a new playbook

Creates a new playbook from a YAML definition. The playbook is validated on creation and becomes available for execution immediately. Playbooks define steps, agent assignments, triggers, rubrics for success, and optional approval gates.

Request body

namestringrequired

Human-readable name for the playbook.

descriptionstring

Short summary of what the playbook does.

yamlstringrequired

The playbook definition as a YAML string. Validated on creation.

tagsstring[]

Labels used to organize and filter playbooks.

Request Body

json

{
  "name": "Weekly Market Report",
  "description": "Research market trends and generate a structured PDF report every Monday.",
  "yaml": "name: Weekly Market Report\ntrigger:\n  schedule: '0 9 * * MON'\nsteps:\n  - role: researcher\n    action: research\n    params:\n      topic: 'market trends'\n      depth: comprehensive\n  - role: writer\n    action: compile_report\n    params:\n      format: pdf\n      sections: [summary, data, recommendations]\nrubric:\n  min_sources: 5\n  max_cost: 5.00",
  "tags": ["research", "weekly", "automated"]
}

The yaml field carries the playbook definition as an escaped string. Unescaped, the definition from the request above looks like this:

playbook.yml

yaml

name: Weekly Market Report
trigger:
  schedule: '0 9 * * MON'
steps:
  - role: researcher
    action: research
    params:
      topic: 'market trends'
      depth: comprehensive
  - role: writer
    action: compile_report
    params:
      format: pdf
      sections: [summary, data, recommendations]
rubric:
  min_sources: 5
  max_cost: 5.00

Response

json

{
  "success": true,
  "data": {
    "id": "pb_w33kly",
    "company_id": "co_r3s34rch",
    "name": "Weekly Market Report",
    "description": "Research market trends and generate a structured PDF report every Monday.",
    "status": "active",
    "step_count": 2,
    "tags": ["research", "weekly", "automated"],
    "trigger": {
      "type": "schedule",
      "schedule": "0 9 * * MON"
    },
    "created_at": "2026-05-25T10:00:00Z"
  },
  "meta": {
    "credits_used": 3,
    "credits_remaining": 9966
  }
}

Tip

You can also upload playbook YAML directly using the CLI with capx playbook create --file playbook.yml. See the CLI Reference for details.

List Playbooks

GET/companies/:id/playbooksList all playbooks in a company

Returns a paginated list of all playbooks in the specified company. You can filter by status and tags.

Parameter	Type	Description
status	string	Filter: active, paused, archived
tag	string	Filter by tag (can be specified multiple times)
limit	integer	Results per page (default 25, max 100)
cursor	string	Pagination cursor

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/playbooks?status=active" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": [
    {
      "id": "pb_w33kly",
      "name": "Weekly Market Report",
      "status": "active",
      "step_count": 2,
      "last_run_at": "2026-05-19T09:00:00Z",
      "run_count": 12,
      "tags": ["research", "weekly", "automated"]
    }
  ],
  "meta": {
    "cursor": null,
    "has_more": false,
    "credits_used": 1,
    "credits_remaining": 9965
  }
}

Get a Playbook

GET/companies/:id/playbooks/:playbookIdRetrieve a single playbook

Returns the full definition of a playbook, including its YAML source, trigger configuration, step details, rubric, and execution statistics.

Request

bash

curl https://api.capx.ai/v1/companies/co_r3s34rch/playbooks/pb_w33kly \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "id": "pb_w33kly",
    "company_id": "co_r3s34rch",
    "name": "Weekly Market Report",
    "description": "Research market trends and generate a structured PDF report every Monday.",
    "status": "active",
    "yaml": "name: Weekly Market Report\ntrigger:\n  schedule: '0 9 * * MON'\n...",
    "steps": [
      { "role": "researcher", "action": "research" },
      { "role": "writer", "action": "compile_report" }
    ],
    "trigger": {
      "type": "schedule",
      "schedule": "0 9 * * MON"
    },
    "rubric": {
      "min_sources": 5,
      "max_cost": 5.00
    },
    "run_count": 12,
    "avg_run_cost": 3.20,
    "avg_run_duration": 480,
    "created_at": "2026-05-25T10:00:00Z"
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9964
  }
}

Execute a Playbook

POST/companies/:id/playbooks/:playbookId/runTrigger a playbook run

Manually triggers a playbook run. This is independent of the playbook's scheduled trigger and can be used for ad-hoc execution. You can pass runtime parameters that override defaults defined in the playbook YAML.

Request body

paramsobject

Runtime parameters that override the defaults defined in the playbook YAML.

Request Body

json

{
  "params": {
    "topic": "AI infrastructure funding Q2 2026",
    "depth": "deep"
  }
}

Response

json

{
  "success": true,
  "data": {
    "run_id": "run_m4rk3t",
    "playbook_id": "pb_w33kly",
    "status": "running",
    "params": {
      "topic": "AI infrastructure funding Q2 2026",
      "depth": "deep"
    },
    "started_at": "2026-05-25T15:00:00Z"
  },
  "meta": {
    "credits_used": 2,
    "credits_remaining": 9962
  }
}

Note

Playbook runs execute asynchronously. Use the run status endpoints or webhooks to track progress and receive completion notifications.

List Playbook Runs

GET/companies/:id/playbooks/:playbookId/runsList all runs of a playbook

Returns a paginated list of all runs for a specific playbook, ordered by most recent first. Filter by status to find running, completed, or failed executions.

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/playbooks/pb_w33kly/runs?status=completed&limit=5" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": [
    {
      "run_id": "run_m4rk3t",
      "status": "completed",
      "cost": 2.85,
      "duration": 420,
      "started_at": "2026-05-25T15:00:00Z",
      "completed_at": "2026-05-25T15:07:00Z"
    },
    {
      "run_id": "run_pr3v10us",
      "status": "completed",
      "cost": 3.10,
      "duration": 510,
      "started_at": "2026-05-19T09:00:00Z",
      "completed_at": "2026-05-19T09:08:30Z"
    }
  ],
  "meta": {
    "cursor": "eyJydW4iOiJydW5fcHIzdjEwdXMifQ",
    "has_more": true,
    "credits_used": 1,
    "credits_remaining": 9961
  }
}

Get a Playbook Run

GET/companies/:id/playbooks/:playbookId/runs/:runIdRetrieve details of a specific run

Returns the full details of a specific playbook run, including step-by-step execution results, cost breakdown, outputs, and any errors encountered.

Request

bash

curl https://api.capx.ai/v1/companies/co_r3s34rch/playbooks/pb_w33kly/runs/run_m4rk3t \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "run_id": "run_m4rk3t",
    "playbook_id": "pb_w33kly",
    "status": "completed",
    "params": {
      "topic": "AI infrastructure funding Q2 2026",
      "depth": "deep"
    },
    "steps": [
      {
        "index": 0,
        "role": "researcher",
        "agent_id": "ag_4n4ly5t",
        "action": "research",
        "status": "completed",
        "cost": 1.60,
        "duration": 240,
        "output": { "sources_found": 8, "data_points": 47 }
      },
      {
        "index": 1,
        "role": "writer",
        "agent_id": "ag_wr1t3r",
        "action": "compile_report",
        "status": "completed",
        "cost": 1.25,
        "duration": 180,
        "output": { "artifact": "report_ai_infra_q2_2026.pdf" }
      }
    ],
    "total_cost": 2.85,
    "duration": 420,
    "started_at": "2026-05-25T15:00:00Z",
    "completed_at": "2026-05-25T15:07:00Z"
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9960
  }
}

Run Statuses

Status	Description
queued	Run is waiting to start
running	Run is currently executing steps
completed	All steps finished successfully
failed	One or more steps failed and the run was aborted
cancelled	Run was manually cancelled

Writing PlaybooksTyped workflow pipelines with inputs, outputs, and rubrics.Tasks APIAssign work, track status, and read results.CLI ReferenceManage playbooks from the terminal with capx playbook commands.

PreviousTasks NextActivity & Costs