Start a playbook run in a space

POST

/spaces/:spaceId/playbook-runs

POST

/spaces/:spaceId/playbook-runs

$ curl -X POST https://api.cloudraker.com/spaces/spaceId/playbook-runs \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "playbookId": "pb-8f3a2c7d",
>   "fileScope": {
>     "mode": "space"
>   }
> }'

1 {
2   "data": {
3     "id": "run-4b9d2e1f",
4     "spaceId": "space-12345",
5     "playbookId": "pb-8f3a2c7d",
6     "playbookVersion": 3,
7     "playbookName": "Incident Response Workflow",
8     "status": "running",
9     "fileScope": {
10       "mode": "space"
11     },
12     "taskProgress": {
13       "total": 5,
14       "completed": 2
15     },
16     "pendingApproval": {
17       "id": "approval-9876",
18       "kind": "pre",
19       "actionName": "Escalate Incident",
20       "requestedAt": "2024-01-15T09:30:00Z"
21     },
22     "result": "In progress",
23     "error": "",
24     "startedBy": "user-42",
25     "createdAt": "2024-01-15T09:30:00Z",
26     "updatedAt": "2024-01-15T10:00:00Z",
27     "finishedAt": "2024-01-15T12:00:00Z",
28     "currentActivity": "Waiting for escalation approval",
29     "snapshot": {
30       "playbookId": "pb-8f3a2c7d",
31       "version": 3,
32       "name": "Incident Response Workflow",
33       "description": "A playbook to handle security incidents efficiently.",
34       "tasks": [
35         {
36           "id": "task-001",
37           "title": "Identify Incident",
38           "dependsOn": [],
39           "status": "completed",
40           "summary": "Incident identified and logged.",
41           "completedAt": "2024-01-15T09:45:00Z",
42           "instructions": "Gather all relevant logs and alerts."
43         }
44       ],
45       "actions": [
46         {
47           "installedActionId": "action-esc-01",
48           "preApproval": true,
49           "postApproval": false,
50           "dependsOn": [
51             "task-001"
52           ],
53           "actionSlug": "escalate-incident",
54           "actionName": "Escalate Incident",
55           "trigger": "agent",
56           "browserSession": {
57             "status": "pairing",
58             "createdAt": "2024-01-15T09:30:00Z"
59           }
60         }
61       ],
62       "fileScope": {
63         "mode": "space"
64       }
65     }
66   }
67 }

Starts a new durable agentic run of a playbook in this space. Authorization: requires space:contribute on the space (org admins bypass); missing permission → 403. Body: playbookId (required — the playbook to run) and fileScope, which is either { mode: "space" } (the agent may see all files in the space) or { mode: "picked", fileIds: [...] } (1–200 explicit file ids). spaceType is resolved from the space record server-side and is NOT accepted from the caller. Returns 404 when the space does not exist. On success returns 201 { data: PlaybookRun } — the created run with its immutable snapshot of the playbook captured at launch time.

Starts a new durable agentic run of a playbook in this space. Authorization: requires `space:contribute` on the space (org admins bypass); missing permission → 403. Body: `playbookId` (required — the playbook to run) and `fileScope`, which is either `{ mode: "space" }` (the agent may see all files in the space) or `{ mode: "picked", fileIds: [...] }` (1–200 explicit file ids). `spaceType` is resolved from the space record server-side and is NOT accepted from the caller. Returns 404 when the space does not exist. On success returns 201 `{ data: PlaybookRun }` — the created run with its immutable snapshot of the playbook captured at launch time.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

spaceIdstringRequired

Request

The space type is resolved from the space record and is not accepted here.

playbookIdstringRequired>=1 character

fileScopeobjectRequired

Response

The created playbook run.

dataobject

Errors

404

Not Found Error