Playbooks API

Per-workspace executable agent specs. A PlaybookSpec pairs a lead source with a strategy and optional adaptation rules; runs are recorded against the spec and tracked over time.

See the Playbooks guide for the concept overview and spec schema.

All endpoints require auth + workspace context. Read-only workspaces return 403 on mutating calls.

List

GET /api/v1/playbooks
Authorization: Bearer <token>

{ "playbooks": [ /* PlaybookSpec[] */ ] }

Create

POST /api/v1/playbooks
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "name": "Series B SaaS. New head of growth",
  "mode": "outbound",
  "buddyId": "prospect",
  "strategy": {
    "hypothesis": "...",
    "successMetric": "meeting_booked",
    "successTarget": 3
  }
}

Required fields: name, mode, buddyId, strategy.hypothesis. Missing any of these returns 400. The server assigns id, createdAt, updatedAt, and createdBy. Defaults: status=draft, leadSource.kind=manual, strategy.kind=gtm-execution, adaptation={ enabled:true, minSampleSize:50, pivotWindowDays:3, maxPivotsPerWeek:2 }.

Returns 201 with { "playbook": <spec> }.

Get

GET /api/v1/playbooks/:id

Returns { "playbook": <spec> } or 404.

Update

PUT /api/v1/playbooks/:id
Content-Type: application/json
 
{ "status": "active", "strategy": { "successTarget": 5 } }

Partial update. Nested objects (leadSource, strategy, adaptation) shallow-merge. Unknown fields are silently dropped. Invalid enum values (e.g. status: "foo") are ignored.

Delete

DELETE /api/v1/playbooks/:id

Returns { "ok": true } or 404.

Record a run

POST /api/v1/playbooks/:id/run

Creates a run row with status=running and initial metrics { samples:0, successes:0, metricValue:0 }. Returns 201 with { "run": <run> }.

The actual agent invocation happens client-side via playbook-runtime.ts (opens a buddy chat with a structured prompt built from the spec). This endpoint just records that a run started.

List runs

GET /api/v1/playbooks/:id/runs

Returns { "runs": [ /* PlaybookRun[] */ ] } ordered by startedAt.

Field reference