# Start an agent run Starts the model working on the conversation's next turn and answers 202 with the run's id at once; the work happens after the response. A client-chosen `runId` makes the call safe to retry: calling it again with the same id — whether the first call already created the run or is still being admitted — answers the same id rather than starting a second run. The run's progress and output follow on the journal and `runs.get`; a tool call that needs consent opens an approval and pauses the run until `approvals.approve` or `approvals.deny` decides it. `POST /v1/users/{userId}/agent-runs` ## Authentication Both headers are required. - Header: `X-Api-Key: YOUR_API_KEY` - Header: `Authorization: Bearer YOUR_USER_TOKEN` ## Path parameters ```json [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "userId", "required": true, "description": "The user in the path; must equal the token's own account." } ] ``` ## Request body ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "text": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "The run's seed instruction, up to 32768 characters." }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "description": "The strict terminal output contract validated and frozen during admission.", "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "What the terminal result means, shown beside the run's output.", "type": "string", "maxLength": 4096 }, "schema": { "description": "A bounded, strict JSON Schema object (`type: \"object\"`, `additionalProperties: false`) the run's terminal output must satisfy." } }, "required": [ "name", "schema" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Bounds on this run beyond its seed text: which tools it may reach, and its terminal output contract." }, "runId": { "description": "A client-chosen id that makes the start safe to retry: calling this again with the same id — whether the first call already created the run or is still being admitted — answers the same run rather than starting a second one.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "conversationId", "text" ], "additionalProperties": false } } } } ``` ## Request example Illustrative request. Replace the host, credentials and resource IDs with your own. If a request file is shown, create it from the schema above. Review the requested action before sending it. ```sh curl --request POST 'https://api.example.test/v1/users/YOUR_USER_ID/agent-runs' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_USER_TOKEN' \ --header 'Content-Type: application/json' \ --data-binary '@request.json' ``` ## Responses ### 202 The run's id; the same id again when this exact `runId` was already accepted. ```json { "description": "The run's id; the same id again when this exact `runId` was already accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The started run's id; the same value sent, when one was sent." } }, "required": [ "runId" ] } } } } ``` ### 400 The request could not be read as this operation expects. - `invalid_input` — the body or query failed validation; `issues` names each field - `invalid_cursor` — the `cursor` is not one this list minted ```json { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 401 A credential is missing, invalid or expired. - `partner_key_required` — no `X-Api-Key` header was sent - `partner_key_invalid` — the `X-Api-Key` is unknown or revoked - `credential_expired` — the user token has expired; obtain a fresh one ```json { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 403 The credentials are valid but may not do this. - `subject_mismatch` — the `{userId}` in the path is not the token's user - `account_disabled` — an operator disabled the account - `origin_rejected` — a browser `Origin` other than the configured web origin ```json { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 404 The resource is missing, belongs to someone else, or its id is malformed: all three answer alike. ```json { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 409 The operation lost to the current state. - `run_active` — a run already holds this conversation - `budget_exhausted` — the user's spend headroom is gone, or an operator froze it - `execution_capacity` — no execution capacity is free right now; `retryable` says whether to try again - `execution_unavailable` — the execution engine could not take the work - `profile_unknown_tool` — the run profile names a tool this deployment does not have - `deployment_paused` — an operator paused a deployment control; nothing was admitted or fired - `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed ```json { "description": "The operation lost to the current state.\n\n- `run_active` — a run already holds this conversation\n- `budget_exhausted` — the user's spend headroom is gone, or an operator froze it\n- `execution_capacity` — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` — the execution engine could not take the work\n- `profile_unknown_tool` — the run profile names a tool this deployment does not have\n- `deployment_paused` — an operator paused a deployment control; nothing was admitted or fired\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 412 The identity is verified but has no account yet. - `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first ```json { "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 413 The body exceeds the size this deployment accepts. ```json { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 429 A limiter refused the request; honour `Retry-After`. - `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After` ```json { "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 500 A fault on our side; quote `requestId` when reporting it. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ### 503 The replica is draining or a dependency did not answer; `retryable` says whether to try again. - `internal` — a fault on our side; quote `requestId` when reporting it ```json { "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } ``` ## Complete OpenAPI definition The exact operation and all referenced components, including recursive schemas. ```json { "operation": { "operationId": "runs.start", "summary": "Start an agent run", "tags": [ "agent-runs" ], "description": "Starts the model working on the conversation's next turn and answers 202 with the run's id at once; the work happens after the response. A client-chosen `runId` makes the call safe to retry: calling it again with the same id — whether the first call already created the run or is still being admitted — answers the same id rather than starting a second run. The run's progress and output follow on the journal and `runs.get`; a tool call that needs consent opens an approval and pauses the run until `approvals.approve` or `approvals.deny` decides it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The conversation's id." }, "text": { "type": "string", "minLength": 1, "maxLength": 32768, "description": "The run's seed instruction, up to 32768 characters." }, "profile": { "type": "object", "properties": { "tools": { "description": "The only tools this run may reach. Absent means every registered tool.", "maxItems": 64, "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." } }, "outputContract": { "description": "The strict terminal output contract validated and frozen during admission.", "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "A tool's name: lowercase, starting with a letter, letters, digits and underscores only." }, "description": { "description": "What the terminal result means, shown beside the run's output.", "type": "string", "maxLength": 4096 }, "schema": { "description": "A bounded, strict JSON Schema object (`type: \"object\"`, `additionalProperties: false`) the run's terminal output must satisfy." } }, "required": [ "name", "schema" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Bounds on this run beyond its seed text: which tools it may reach, and its terminal output contract." }, "runId": { "description": "A client-chosen id that makes the start safe to retry: calling this again with the same id — whether the first call already created the run or is still being admitted — answers the same run rather than starting a second one.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "conversationId", "text" ], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "userId", "required": true, "description": "The user in the path; must equal the token's own account." } ], "security": [ { "apiKey": [], "userToken": [] } ], "responses": { "202": { "description": "The run's id; the same id again when this exact `runId` was already accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The started run's id; the same value sent, when one was sent." } }, "required": [ "runId" ] } } } }, "400": { "$ref": "#/components/responses/InvalidInput" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The operation lost to the current state.\n\n- `run_active` — a run already holds this conversation\n- `budget_exhausted` — the user's spend headroom is gone, or an operator froze it\n- `execution_capacity` — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` — the execution engine could not take the work\n- `profile_unknown_tool` — the run profile names a tool this deployment does not have\n- `deployment_paused` — an operator paused a deployment control; nothing was admitted or fired\n- `stop_pending` — a stop is already in progress and its cleanup is not yet confirmed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "$ref": "#/components/responses/AccountNotProvisioned" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/Internal" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "components": { "responses": { "InvalidInput": { "description": "The request could not be read as this operation expects.\n\n- `invalid_input` — the body or query failed validation; `issues` names each field\n- `invalid_cursor` — the `cursor` is not one this list minted", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "A credential is missing, invalid or expired.\n\n- `partner_key_required` — no `X-Api-Key` header was sent\n- `partner_key_invalid` — the `X-Api-Key` is unknown or revoked\n- `credential_expired` — the user token has expired; obtain a fresh one", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "The credentials are valid but may not do this.\n\n- `subject_mismatch` — the `{userId}` in the path is not the token's user\n- `account_disabled` — an operator disabled the account\n- `origin_rejected` — a browser `Origin` other than the configured web origin", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "The resource is missing, belongs to someone else, or its id is malformed: all three answer alike.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "AccountNotProvisioned": { "description": "The identity is verified but has no account yet.\n\n- `account_not_provisioned` — the identity is verified but has no account yet; call `users.ensure` first", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PayloadTooLarge": { "description": "The body exceeds the size this deployment accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "TooManyRequests": { "description": "A limiter refused the request; honour `Retry-After`.\n\n- `rate_limited` — the per-key or per-user limit is spent; honour `Retry-After`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Internal": { "description": "A fault on our side; quote `requestId` when reporting it.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unavailable": { "description": "The replica is draining or a dependency did not answer; `retryable` says whether to try again.\n\n- `internal` — a fault on our side; quote `requestId` when reporting it", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The kind of problem as a URN, `urn:fin:error:`; stable, compare against it" }, "title": { "type": "string", "description": "The kind's human title, for logs; never parse it" }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "The HTTP status, repeated in the body" }, "reason": { "description": "The machine-readable why. One of:\n\n- `run_active` (409) — a run already holds this conversation\n- `budget_exhausted` (409) — the user's spend headroom is gone, or an operator froze it\n- `approval_not_pending` (409) — the approval was already decided or has expired, or its id does not exist or belongs to a different conversation\n- `execution_capacity` (409) — no execution capacity is free right now; `retryable` says whether to try again\n- `execution_unavailable` (409) — the execution engine could not take the work\n- `stop_pending` (409) — a stop is already in progress and its cleanup is not yet confirmed\n- `automation_changed` (409) — the `revision` sent is stale; reload the automation\n- `automation_held` (409) — an operator holds the automation; it fires again when released\n- `automation_invalid` (409) — the automation's definition cannot run as written\n- `automation_completed` (409) — the automation has finished for good and cannot fire again\n- `automation_limit` (409) — the user already has as many automations as the deployment allows\n- `profile_unknown_tool` (409) — the run profile names a tool this deployment does not have\n- `deployment_paused` (409) — an operator paused a deployment control; nothing was admitted or fired\n- `run_not_active` (409) — the run named in the path is not the conversation's live run\n- `withdrawal_changed` (409) — the withdrawal cannot be prepared or confirmed as asked: the balance no longer covers it, its terms changed or expired, or it is already in progress\n- `credential_expired` (401) — the user token has expired; obtain a fresh one\n- `account_disabled` (403) — an operator disabled the account\n- `account_not_provisioned` (412) — the identity is verified but has no account yet; call `users.ensure` first\n- `provider_unavailable` (503) — an external provider the call depends on did not answer\n- `engine_unavailable` (503) — the execution engine did not answer\n- `invalid_input` (400) — the body or query failed validation; `issues` names each field\n- `internal` (500) — a fault on our side; quote `requestId` when reporting it\n- `partner_key_required` (401) — no `X-Api-Key` header was sent\n- `partner_key_invalid` (401) — the `X-Api-Key` is unknown or revoked\n- `subject_mismatch` (403) — the `{userId}` in the path is not the token's user\n- `origin_rejected` (403) — a browser `Origin` other than the configured web origin\n- `permission_required` (403) — the operator credential lacks the scope this call needs\n- `rate_limited` (429) — the per-key or per-user limit is spent; honour `Retry-After`\n- `stream_capacity` (429) — no stream socket is free on this replica or for this user; honour `Retry-After`\n- `invalid_cursor` (400) — the `cursor` is not one this list minted", "type": "string", "enum": [ "run_active", "budget_exhausted", "approval_not_pending", "execution_capacity", "execution_unavailable", "stop_pending", "automation_changed", "automation_held", "automation_invalid", "automation_completed", "automation_limit", "profile_unknown_tool", "deployment_paused", "run_not_active", "withdrawal_changed", "credential_expired", "account_disabled", "account_not_provisioned", "provider_unavailable", "engine_unavailable", "invalid_input", "internal", "partner_key_required", "partner_key_invalid", "subject_mismatch", "origin_rejected", "permission_required", "rate_limited", "stream_capacity", "invalid_cursor" ] }, "requestId": { "type": "string", "description": "The id Fin used for this request; quote it when reporting a problem" }, "retryable": { "type": "boolean", "description": "Whether repeating the same request later can succeed without changing it" }, "detail": { "description": "Only on `invalid_input`: which part of the request failed validation", "type": "string" }, "issues": { "description": "Only on `invalid_input`: one entry per failing field", "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "The JSON pointer of the failing field; empty for the root object" }, "message": { "type": "string", "description": "Why the field failed" } }, "required": [ "path", "message" ] } } }, "required": [ "type", "title", "status", "requestId", "retryable" ], "description": "RFC 9457 problem details: what every error response carries. Never a provider's message, a query or a stack." } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }, "userToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } } ```