Invoke an agent

POST

https://api.cloudraker.com/v1/agents/:id/invoke

POST

/v1/agents/:id/invoke

$ curl -X POST https://api.cloudraker.com/v1/agents/id/invoke \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "input": "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 }

Runs an agent on an instruction — the prompt-shaped door. Give it input in plain words and, optionally, files; the agent plans and executes from there. This is the same runtime as POST /v1/agent-runs, minus the requirement to lead with files.

Sync by default. ?wait=<seconds> (default 60, max 120) holds the request; a run that outlives the window answers 202 with a statusUrl to poll. Steering, approvals, tasks, timeline and result all use the existing /v1/agent-runs/{id} surface.

Learn more: Agents guide

Runs an agent on an instruction — the prompt-shaped door. Give it `input` in plain words and, optionally, `files`; the agent plans and executes from there. This is the same runtime as `POST /v1/agent-runs`, minus the requirement to lead with files. **Sync by default.** `?wait=<seconds>` (default 60, max 120) holds the request; a run that outlives the window answers `202` with a `statusUrl` to poll. Steering, approvals, tasks, timeline and result all use the existing `/v1/agent-runs/{id}` surface. **Learn more:** [Agents guide](https://docs.cloudraker.com/capabilities/agents)

Authentication

AuthorizationBearer

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

Path parameters

idstringRequired

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.

inputstringRequired1-4000 characters

What you want done, in plain words. Frozen into the run — a later instruction is a steer, not a rewrite.

fileslist of objectsOptional

Files the agent works on. Omit entirely for a prompt-only run.

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 headers

idempotent-replaystringOptional

true when this response replays an earlier request.

Response

The run finished (or blocked on a person) inside the wait window.

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

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error