Start an agent run in a space

POST

https://api.cloudraker.com/v1/spaces/:spaceId/agents

POST

/v1/spaces/:spaceId/agents

$ curl -X POST https://api.cloudraker.com/v1/spaces/spaceId/agents \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "agent": "string",
>   "files": [
>     {
>       "url": "string"
>     }
>   ]
> }'

1 {
2   "object": "string",
3   "id": "agr_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
4   "agent": {
5     "id": "string",
6     "name": "string",
7     "version": 1.1
8   },
9   "input": {
10     "files": [
11       {
12         "id": "string"
13       }
14     ]
15   },
16   "status": "queued",
17   "progress": {
18     "tasks": {
19       "total": 1.1,
20       "completed": 1.1
21     }
22   },
23   "tasks": [
24     {
25       "id": "string",
26       "title": "string",
27       "executor": "agent",
28       "status": "pending",
29       "summary": "string",
30       "completedAt": "string",
31       "note": "string"
32     }
33   ],
34   "statusUrl": "string",
35   "createdAt": "string",
36   "expiresAt": "string",
37   "finishedAt": "string",
38   "waiting": {
39     "approvals": 1.1,
40     "tasks": 1.1,
41     "summary": "string"
42   },
43   "paused": {
44     "reason": "model_error"
45   },
46   "approvals": [
47     {
48       "id": "string",
49       "kind": "before",
50       "action": "string",
51       "requestedAt": "string",
52       "files": [
53         {
54           "id": "string",
55           "name": "string"
56         }
57       ],
58       "rationale": "string",
59       "params": {}
60     }
61   ],
62   "incomplete": true,
63   "result": "string",
64   "output": {
65     "files": [
66       {
67         "id": "string",
68         "name": "string",
69         "url": "string"
70       }
71     ]
72   },
73   "error": {
74     "code": "string",
75     "message": "string"
76   },
77   "metadata": {}
78 }

Starts an agent inside this space: the run and its input files live there, so anything the agent files stays after the run ends.

Same body, same wait semantics and same run object as POST /v1/agent-runs — read the run back at GET /v1/spaces/{spaceId}/agents/{runId}, and steer, approve or cancel it on the ordinary /v1/agent-runs/{id} routes.

Learn more: Spaces

Starts an agent inside this space: the run and its input files live there, so anything the agent files stays after the run ends. Same body, same wait semantics and same run object as `POST /v1/agent-runs` — read the run back at `GET /v1/spaces/{spaceId}/agents/{runId}`, and steer, approve or cancel it on the ordinary `/v1/agent-runs/{id}` routes. **Learn more:** [Spaces](https://docs.cloudraker.com/developers/spaces)

Authentication

AuthorizationBearer

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

Path parameters

spaceIdstringRequired

Query parameters

waitintegerOptional0-120Defaults to 60

How many seconds to hold the request open. Releases early the moment the run finishes or blocks on a person. Maximum 120; 0 returns immediately.

Request

This endpoint expects an object.

agentstringRequired>=1 character

The agent to run, by id.

fileslist of objectsRequired

The files the agent works on, up to 200.

metadatamap from strings to anyOptional

Arbitrary JSON you attach to the run and get back on every read of it.

Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.

webhookobjectOptional

Where to deliver this run’s events, given one of two ways.

{ "url": "…" } — a one-off https endpoint for this run only.
{ "id": "whe_…" } — a saved endpoint from POST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.

Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.

Response

The finished run.

object"agent_run"

idstring

agentobject

inputobject

statusenum

Where the agent run is in its life.

Status	Meaning
`queued`	Accepted; its files are still being prepared
`processing`	The agent is working
`waiting`	Blocked on a person — see `waiting`, `approvals` and `tasks[]`
`paused`	Stopped short of finishing and resumable; not a failure
`completed`	Finished; `result` and `output` are populated
`failed`	Finished without producing a result
`cancelled`	Stopped on request
`expired`	Reached its `expiresAt` without finishing

completed, failed, cancelled and expired are terminal. A completed run that still had outstanding work also carries incomplete: true.

progressobject

taskslist of objects

statusUrlstring

createdAtstring

expiresAtstring or null

The run’s deadline: about seven days after it starts, an unfinished run parks itself for good and its status becomes expired. null once the run is finished. Files and anything the run already filed are never taken back.

finishedAtstring or null

waitingobjectOptional

What is blocking the run. Present while status is waiting.

pausedobjectOptional

Why the run parked. Present while status is paused. A paused run keeps everything it produced and can be started again.

approvalslist of objectsOptional

Sign-offs the run is waiting on, oldest first.

incompletebooleanOptional

Present and true on a completed run that still had outstanding work — read tasks[] to see what.

resultstringOptional

The agent's closing summary.

outputobjectOptional

Files attached to the run while its steps were completed, each with a signed download link valid for about an hour.

errorobjectOptional

Why the run failed. Present whenever status is failed.

metadatamap from strings to anyOptional

Errors

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error