Start a playbook run in a space
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). Optional `prompt` (1–4000 chars) is the request that founds the run: it is frozen into the run’s immutable snapshot and stays part of the agent’s standing instructions for every turn — use `steer` to say anything after launch. `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
spaceId
Request
The space type is resolved from the space record and is not accepted here.
playbookId
fileScope
prompt
The request that founds the run, frozen into its immutable snapshot and kept in the agent’s standing instructions. Use steer for anything after launch.
Response
The created playbook run.
data
Errors
404
Not Found Error