Start a run
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" }}The active products and prices of the app, for a pricing page, with the Stripe publishable key its payment form needs
The active products and prices of the app, for a pricing page, with the Stripe publishable key its payment form needs. Readable signed out.
List runs
Active root runs by default — it answers *what is my agent doing right now* without needing to already hold a `runUid`.