Start an action run in a space

POST

/spaces/:spaceId/runs

POST

/spaces/:spaceId/runs

$ curl -X POST https://api.cloudraker.com/spaces/spaceId/runs \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "actionSlug": "contract-terms-extraction",
>   "fileIds": [
>     "file_9a8b7c6d5e4f3g2h1i0j"
>   ]
> }'

201Created

1 {
2   "data": {
3     "id": "run_01J9K8L7M6N5O4P3Q2R1",
4     "spaceId": "space_1234567890abcdef",
5     "actionSlug": "contract-terms-extraction",
6     "actionVersion": 3,
7     "installedActionId": "action_9876543210fedcba",
8     "playbookRunId": "playbook_1122334455aabbcc",
9     "status": "running",
10     "error": "",
11     "artifacts": [
12       {
13         "id": "artifact_0011223344556677",
14         "kind": "link",
15         "title": "Extracted Contract Terms Summary",
16         "url": "https://app.cloudraker.com/spaces/space_1234567890abcdef/artifacts/artifact_0011223344556677",
17         "open": "tab"
18       }
19     ],
20     "awaitingInput": [],
21     "documents": [
22       {
23         "fileId": "file_9a8b7c6d5e4f3g2h1i0j",
24         "name": "Contract_Agreement_2024.pdf",
25         "contentType": "application/pdf"
26       }
27     ],
28     "outputs": [
29       {
30         "fileId": "output_5566778899aabbcc",
31         "kind": "json",
32         "key": "extracted_terms.json",
33         "size": 24567
34       }
35     ],
36     "timeoutSeconds": 300,
37     "lastEventAt": "2024-01-15T09:30:00Z",
38     "createdAt": "2024-01-15T09:29:45Z",
39     "createdBy": "user_42f1e3d7c9a8b6e5",
40     "finishedAt": ""
41   }
42 }

Starts a new action run scoped to the space in the path. Requires space:contribute on that space (denied → 403). The space is taken from the path — a spaceId in the body never scopes the run. Body: actionSlug (installed action to run, required, non-empty), fileIds (1–100 file IDs from the space to feed the run, each non-empty), optional params (free-form object passed to the action). Returns 201 { data: ActionRun }; the run starts in status running — poll getRun for awaiting_input / done / failed plus its outputs and artifacts.

Starts a new action run scoped to the space in the path. Requires `space:contribute` on that space (denied → 403). The space is taken from the path — a `spaceId` in the body never scopes the run. Body: `actionSlug` (installed action to run, required, non-empty), `fileIds` (1–100 file IDs from the space to feed the run, each non-empty), optional `params` (free-form object passed to the action). Returns 201 `{ data: ActionRun }`; the run starts in status `running` — poll `getRun` for `awaiting_input` / `done` / `failed` plus its `outputs` and `artifacts`.

Authentication

AuthorizationBearer

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

Path parameters

spaceIdstringRequired

Request

A spaceId in the body is ignored: the run is scoped by the path.

actionSlugstringRequired>=1 character

Installed action to run, by id or per-organization slug.

fileIdslist of stringsRequired

Files from this space to feed the run.

paramsmap from strings to anyOptional

Per-run parameters for the action.

Response

The started run.

dataobject