> ## Documentation Index > Fetch the complete documentation index at: https://docs.stefanbrain.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Follow the content contract in AGENTS.md. > Treat text as the canonical explanation; video and screenshots enhance it. > Do not publish unverified product behavior or duplicate an existing canonical article. # Start an agent run ## OpenAPI ````yaml /developers/openapi/stefanbrain-v1.json post /api/developers/v1/runs openapi: 3.1.0 info: title: StefanBrain Developer API version: 1.0.0 description: >- REST access to StefanBrain agent runs, tools, and jobs. Authenticate with an API key from Settings → Developers. REST usage bills your prepaid API wallet at the published per-token rates (see https://docs.stefanbrain.com/developers/pricing); the MCP endpoint (/api/developers/v1/mcp, not described here) is member pricing from your plan pool. Human documentation: https://docs.stefanbrain.com/developers servers: - url: https://stefanbrain.com security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: tools description: Directly invocable StefanBrain tools. - name: jobs description: Long-running tool jobs (poll for results). - name: runs description: Agentic chat runs with event streams. - name: files description: Workspace files agent runs produced in a chat. - name: media description: 'Stored Meta ad media facts: video transcripts on demand.' - name: feedback description: >- Tell StefanBrain where the API got in your way, and read the team's replies. paths: /api/developers/v1/runs: post: tags: - runs summary: Start an agent run operationId: startRun parameters: - name: Idempotency-Key in: header required: false description: >- Safe blind retries: resubmitting the same key returns the ORIGINAL run's envelope (202 while it is running, the full status once it finished) — no second chat, no second billed run, and attachment staging is skipped. Dedupe window: the same UTC day, like the tools lane. 1-128 chars of A-Z a-z 0-9 _ . : -; invalid values are 400 invalid_idempotency_key. schema: type: string pattern: ^[A-Za-z0-9_.:-]{1,128}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunRequest' multipart/form-data: schema: type: object description: >- A `payload` field carrying the JSON body plus one or more `files` parts for attachments. additionalProperties: true responses: '200': description: >- The run's final status: a sync-mode run ({ sync: true }) that ended inside the sync window (about 90 s from when the request arrived, upload time included), or a keyed replay of a run that already ended. Failed and cancelled runs also return 200; check status. headers: x-wallet-remaining-cents: description: >- Remaining API wallet balance in USD cents after this request's pre-flight check. schema: type: integer x-wallet-resets-at: description: ISO timestamp when the wallet's monthly plan credit next resets. schema: type: string format: date-time content: application/json: schema: $ref: '#/components/schemas/Run' '202': description: >- Run accepted; poll status_url. Also the sync-mode answer when the run outlives the sync window, or a keyed replay of a run still in progress. headers: x-wallet-remaining-cents: description: >- Remaining API wallet balance in USD cents after this request's pre-flight check. schema: type: integer x-wallet-resets-at: description: ISO timestamp when the wallet's monthly plan credit next resets. schema: type: string format: date-time content: application/json: schema: $ref: '#/components/schemas/Run' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Suspended key, missing plan access, or key scoped away from this surface (code api_key_scope_forbidden). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- Chat or project not found for this account (code chat_not_found or project_not_found). content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The chat already has an active run (code agent_run_rejected, with activeRunId when known; retry later or use a separate chat), the chat belongs to a different project (code chat_project_mismatch), or the chat id was deleted and cannot be reused (code chat_id_retired). content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: Attachment payload too large (code attachment_too_large). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Rate limited (codes request_per_minute, request_per_minute_user, request_per_day, user_throttled, user_suspended; Retry-After header when the limit has a reset time, plus limits, observed counts, and reset_at in the body), the runtime has no capacity to start a turn right now (code runtime_capacity_busy, Retry-After: 5), wallet exhausted (code api_wallet_exhausted), key budget exhausted (code api_key_budget_exhausted), or the plan's monthly usage pool spent for OAuth-token traffic (code monthly_usage_limit_reached). content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Unexpected server failure (code internal_error). content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- Transient runtime or infrastructure failure (type service_unavailable_error, or code workspace_busy with Retry-After). Retry transient failures with backoff and the same Idempotency-Key. Code api_wallet_reconciliation_required is a retained billing review hold: contact support instead of retrying or adding credit. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RunRequest: type: object required: - message properties: message: type: string chat: type: string description: >- A chat_... id to continue. Omit it to start the run in a new chat, with or without project. project: type: string description: >- A proj_... id or project UUID. Without chat, the run starts in a new chat inside that project. sync: type: boolean description: >- Hold the connection until the run ends or the sync window closes: about 90 s, counted from when the request arrives (upload time included). A run that ends inside the window returns 200 with its final status; failed and cancelled runs also return 200, so check status. Otherwise the normal 202 envelope; finish by polling. Keyed replays answer at once. Set the HTTP client timeout to 120 s: a dropped connection or 504 does not stop the run. on_busy: type: string enum: - reject description: >- Busy-chat behavior. Only "reject" (default) is supported: an active run returns the 409 chat-busy error. Retry when the active run finishes or use a separate chat. output_config: type: object description: >- Structured output constraint: { format: { type: "json_schema", schema } }. The schema must satisfy strict mode (additionalProperties: false everywhere; every property listed in required). additionalProperties: true additionalProperties: true Run: type: object properties: object: type: string run_id: type: string chat: type: string status: type: string output: type: - string - 'null' description: >- The latest assistant text, or null before there is any. It is the final answer only once status is completed. structured_output: type: - object - 'null' description: >- Parsed JSON of the final answer for runs started with output_config; null when not requested or not completed. turn_state: type: - string - 'null' created_at: type: - string - 'null' format: date-time started_at: type: - string - 'null' format: date-time completed_at: type: - string - 'null' format: date-time cancel_requested: type: boolean last_error: type: - string - 'null' project: type: string user_message: type: string description: Acceptance envelope only (msg_u_... id). assistant_message: type: string description: Acceptance envelope only (msg_a_... id). status_url: type: string description: Acceptance envelope only. events_url: type: string description: Acceptance envelope only. cancel_url: type: string description: Acceptance envelope only. additionalProperties: true Error: type: object required: - error properties: error: type: object required: - message - type properties: message: type: string type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - api_error - service_unavailable_error code: type: string additionalProperties: true additionalProperties: true securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authorization: Bearer stefan_sk_... (API key — bills the API wallet) or stefan_oat_... (OAuth member token — bills your plan pool). apiKeyHeader: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.