Start the agent on a message
Starts the agent bound to your api key. The key implies the agent — a 1:1 binding — so there is no agent id to pass and any supplied in the body is ignored. **Asynchronous by default.** The response is `202` carrying a `runUid` *before* any work begins, so the handle can never be lost to a client timeout. Poll `GET /agent/runs/{runUid}` for progress and the result. Pass `?wait=true` to hold the connection for short calls instead. That wait has a server-side ceiling; when it is reached you receive the same async envelope and the run continues — waiting can degrade into polling, never into an orphaned run. If the agent reaches a step its policy marks high-risk, the run **pauses** rather than proceeding, and `status` becomes `pending_approval`. A human approves it in the console. An `autoApprove` sent by a client is never honoured: an external caller is the least-trusted principal and may only tighten.
Authorization
bearerAuth Authorization for API
In: header
Path Parameters
Your app's unique id. Find it in the console under the app's Settings, or in the URL of any app page.
uuidQuery Parameters
Hold the connection until the run finishes or the server's ceiling is reached.
falseHeader Parameters
Optional. A retry carrying the same key joins the run already in flight rather than starting a second one, and reports that run's state as it is now.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/497f6eca-6276-4993-bfeb-53cbbbba6f08/agent/invoke" \ -H "Content-Type: application/json" \ -d '{ "message": "Refund the last order for customer 4821 and explain why." }'{ "runUid": "string", "status": "string", "resumable": true, "message": "string", "pendingSteps": [ { "stepIndex": 0, "tool": "string", "riskLevel": "string", "input": {} } ], "steps": [ { "stepIndex": 0, "tool": "string", "status": "string", "output": {}, "detail": "string" } ], "actions": { "poll": "string", "dashboard": "string" }}Call one tool directly
Runs exactly this tool, with no model in the loop — deterministic, and cheaper than an orchestrated run when you already know what you want done. The body is the tool's arguments. It accepts `{ "input": { … } }`, `{ "arguments": { … } }`, or the bare argument object. **Governance still applies.** A tool your policy marks high-risk does not execute here either: the response is `202` with a `runUid`, the call waits in the approval inbox, and you poll the run for its outcome. The direct door is faster, not looser. Equivalent to MCP `tools/call`.
List your agent's runs
Active root runs by default — it answers *what is my agent doing right now* without needing to already hold a `runUid`.