Automations

Automations, their runs, and starting them by hand.

GET/v1/automations

List automations

Automations you can see: org-wide ones and those in your projects. Pass project_id for one project's.

Needs automations:readMCP tool list_automations

Query parameters

  • project_idstring or null

    Only this project's automations

Response

  • datalist of AutomationRequired
curl "https://developers.playbookops.ai/v1/automations" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
Response · 200
{
  "data": [
    {
      "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "title": "Call the venue",
      "description": "Confirm the date and ask about parking.",
      "project_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "project_title": "Spring launch",
      "app_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "is_on": false,
      "trigger": "When an item moves to Won",
      "summary": "When an item moves to Won, email the client and create an onboarding task.",
      "startable": false,
      "needs_item": false,
      "published_version": 0,
      "last_run_at": "2026-11-21T15:04:05Z",
      "url": "https://app.playbookops.ai/…"
    }
  ]
}
GET/v1/automations/{automation_id}

Get an automation

One automation: what starts it, what it does in one sentence, and whether it's on.

Needs automations:readMCP tool get_automation

Path parameters

  • automation_idstringRequired

Response

  • idstringRequired
  • titlestringRequired
  • descriptionstring or null
  • project_idstring or null
  • project_titlestring or null
  • app_idstring or null
  • is_onbooleanRequired
  • triggerstring or null

    What starts it, in words

  • summarystring or null

    The whole automation as one sentence

  • startablebooleanRequired

    Published, on and started by hand

  • needs_itemboolean

    Default false.

  • published_versioninteger or null
  • last_run_atstring (date and time) or null
  • urlstringRequired
curl "https://developers.playbookops.ai/v1/automations/AUTOMATION_ID" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
Response · 200
{
  "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "title": "Call the venue",
  "description": "Confirm the date and ask about parking.",
  "project_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "project_title": "Spring launch",
  "app_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "is_on": false,
  "trigger": "When an item moves to Won",
  "summary": "When an item moves to Won, email the client and create an onboarding task.",
  "startable": false,
  "needs_item": false,
  "published_version": 0,
  "last_run_at": "2026-11-21T15:04:05Z",
  "url": "https://app.playbookops.ai/…"
}
GET/v1/automations/{automation_id}/runs

List an automation's runs

An automation's most recent runs, newest first, with their status and any error.

Needs automations:readMCP tool list_automation_runs

Path parameters

  • automation_idstringRequired

Query parameters

  • limitinteger

    1–200, default 25.

Response

  • datalist of AutomationRunRequired
curl "https://developers.playbookops.ai/v1/automations/AUTOMATION_ID/runs?limit=10" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
Response · 200
{
  "data": [
    {
      "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "automation_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "automation_title": "Welcome new clients",
      "status": "in_progress",
      "trigger_type": "…",
      "item_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "item_title": "Call the venue",
      "project_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "record_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "error": "…",
      "is_test": false,
      "started_at": "2026-11-21T15:04:05Z",
      "finished_at": "2026-11-21T15:04:05Z"
    }
  ]
}
GET/v1/automation-runs/{run_id}

Get a run

One run with each step it took, in order, and where it stopped or failed.

Needs automations:readMCP tool get_automation_run

Path parameters

  • run_idstringRequired

Response

  • idstringRequired
  • automation_idstringRequired
  • automation_titlestring or null
  • statusstringRequired
  • trigger_typestringRequired
  • item_idstring or null
  • item_titlestring or null
  • project_idstring or null
  • record_idstring or null
  • errorstring or null
  • is_testboolean

    Default false.

  • started_atstring (date and time)Required
  • finished_atstring (date and time) or null
  • stepslist of RunStepRequired
curl "https://developers.playbookops.ai/v1/automation-runs/RUN_ID" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
Response · 200
{
  "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "automation_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "automation_title": "Welcome new clients",
  "status": "in_progress",
  "trigger_type": "…",
  "item_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "item_title": "Call the venue",
  "project_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "record_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "error": "…",
  "is_test": false,
  "started_at": "2026-11-21T15:04:05Z",
  "finished_at": "2026-11-21T15:04:05Z",
  "steps": [
    {
      "node_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "type": "…",
      "status": "in_progress",
      "error": "…",
      "started_at": "2026-11-21T15:04:05Z",
      "finished_at": "2026-11-21T15:04:05Z"
    }
  ]
}
POST/v1/automations/{automation_id}/runs

Start an automation

Start an automation that's started by hand (its trigger is Manual). Returns the run; poll get_automation_run for progress.

Needs automations:writeChanges data · supports Idempotency-KeyMCP tool start_automation

Path parameters

  • automation_idstringRequired

Body

  • item_idstring or null

    The item to run it on, when the automation needs one

  • record_idstring or null

    For an app's automation: the Live record to run it on, when it needs one

Response

  • idstringRequired
  • automation_idstringRequired
  • automation_titlestring or null
  • statusstringRequired
  • trigger_typestringRequired
  • item_idstring or null
  • item_titlestring or null
  • project_idstring or null
  • record_idstring or null
  • errorstring or null
  • is_testboolean

    Default false.

  • started_atstring (date and time)Required
  • finished_atstring (date and time) or null
  • stepslist of RunStepRequired
curl -X POST "https://developers.playbookops.ai/v1/automations/AUTOMATION_ID/runs" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "item_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "record_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42"
}'
Response · 201
{
  "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "automation_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "automation_title": "Welcome new clients",
  "status": "in_progress",
  "trigger_type": "…",
  "item_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "item_title": "Call the venue",
  "project_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "record_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "error": "…",
  "is_test": false,
  "started_at": "2026-11-21T15:04:05Z",
  "finished_at": "2026-11-21T15:04:05Z",
  "steps": [
    {
      "node_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "type": "…",
      "status": "in_progress",
      "error": "…",
      "started_at": "2026-11-21T15:04:05Z",
      "finished_at": "2026-11-21T15:04:05Z"
    }
  ]
}