Create run from a request

Requires an authenticated tenant principal. Generated from the production route registered in `internal/features/agentrun/inbound/http.go`.

POST/v1/runs

Requires an authenticated tenant principal. Generated from the production route registered in internal/features/agentrun/inbound/http.go.

Authorization

bearerAuth

AuthorizationBearer <token>

Engine-issued API key or tenant-signed JWT.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A one-off task in the caller's own words. The engine finds or makes a hidden personal runner for model and tools (one per person, model and tool set, reused by later requests of the same shape) and starts the run exactly as POST /v1/agents/{id}/runs would: the runner must be active and hold no knowledge, the message passes its input guardrail, the run is owner-only. The 202 carries run_id, status and the runner's agent_id. model is required because the engine has no organization default model.

message*string

The task, in the caller's words. Becomes the run's input.

model*string

The model the runner runs on. Required.

tools?array<string>

Catalog tool names the runner may call (e.g. email.search), each granted at the catalog's default policy. An unknown tool is refused before any run exists. OMITTING the field is what makes the runner a reaching one: it is granted whatever the caller can reach at that moment — their own connections' tools, their MCP servers' tools, and dataset.query when the caller's roleless execution identity can read at least one dataset — re-taken on every request. Naming tools grants exactly those and never re-syncs, so a run that is to call dataset.query must name it here (2026-09-10); an explicit [] is a runner with no tools at all.

max_turns?integer

credit_budget?integer

conversation_id?string

Optional. Makes this a follow-up run on one of the caller's own run conversations: the whole thread so far — earlier runs' tool calls and results included — is the new run's history. 404 for a conversation that is not the caller's own, 400 for one no run opened (a plain chat), 409 while a run on it is still queued, running or awaiting approval.

Formatuuid

connection_ids?array<>

Optional. The caller's own connections the run should reach through when a tool is declared by more than one provider — with Gmail and Outlook both connected, which mailbox email.* reads (2026-09-09). Each id must be one of the caller's own active connections: any other is 404. Empty keeps the engine's default, the longest-standing connection with providers in catalog order. The run view echoes the list as connection_ids.

dataset_id?string

Optional. The dataset the task reads through, and the one dataset.query reads when a call names none (2026-09-10). Checked at create with the identity the RUN will execute under, which carries no roles, so read access must survive losing them: owning the dataset, a user or team grant on it, owning the project it belongs to, or a user or team grant on that project. A dataset shared only through a role:org-member grant is refused. Unknown, unreadable and malformed ids all answer 404, with no way to tell them apart. Stored canonical, so the run view echoes it as the 36-character lowercase uuid — dataset_id, null when the run has none.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/v1/runs" \  -H "Content-Type: application/json" \  -d '{    "message": "string",    "model": "string"  }'

{}

Create run from a request

Authorization

Request Body

Response Body

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

503application/json

2XXapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`