Skip to main content
Agent Runs give your application the full StefanBrain agent. The agent plans the work, selects tools, executes them, and returns the finished response.

Start a run

The request accepts these fields: A run with project addresses a chat inside that project. Project instructions are supplied automatically. When the project-files rollout is enabled for the account, original files are mounted read-only under project/; start with project/INDEX.md. Incognito chats receive no project context. Use the query_projects tool to find project identifiers.

Understand the response

Starting a run normally returns 202 with the run handle: run_id, chat, project (when the chat is in a project), status: "queued", status_url, events_url, and cancel_url. A synchronous run that ends inside the wait window returns 200 with the run’s status body instead: run_id, chat, status, output, structured_output, last_error, cancel_requested, and timestamps. The 200 body has no URLs; the lifecycle paths are:
Poll the status until it is completed, failed, or cancelled.
  • output holds the latest assistant text. It is the final answer only once status is completed.
  • structured_output contains parsed JSON when the run requested a structured response.
  • last_error provides failure detail when the run fails.
  • progress counts the model calls and tool calls the run has started. Its last_activity_at is the time of the run’s newest event. A running run is working while last_activity_at keeps moving. progress is null until the run starts.
Runs execute in the background. Closing the HTTP connection does not cancel the work; you can reconnect and poll again. POST .../cancel returns the run’s status with cancel_requested: true. A running run stops and reports cancelled shortly after. An admitted run that has not started can also be cancelled. Cancellation does not count against rate limits.

Control busy-chat behavior

A chat executes one turn at a time. Busy behavior depends on StefanBrain-Version:
  • 2026-11-01: a new input steers the active turn by default, like the web composer. steered_into_run_id names the run it joined. Its own run_id reads that shared turn and result; no separate turn is billed.
  • 2026-10-20: busy starts return 409, with the blocking run id when known.
On 2026-11-01, send on_busy: "reject" to receive 409 busy instead of steering. Only reject is supported as an explicit option. Your account must be enabled for 2026-11-01 to use that contract. Poll the blocking run and retry after it finishes. Use a separate chat for independent parallel work.

Make a retry idempotent

Add an Idempotency-Key header when you may need to retry a start without knowing whether the first request succeeded:
A repeated key returns the original run: the 202 envelope while it is queued or running, or its final status (200) once it ends. It does not create another chat or start another billed run. The retry must repeat the request: a key first used for a different request (another chat, or other content) is refused with 409 idempotency_conflict, so send a changed request with a new key. A start refused because the chat was busy (409 agent_run_rejected) does not use up its key, so retry it in the same chat with that key. Uploaded files are staged again on every call for now, so a retry that uploads files is refused the same way: send it with a new key. An invalid key returns 400 invalid_idempotency_key. Send a key with every run start. A timeout, dropped connection, or gateway 504 does not stop a run, so a lost response is otherwise a second billed run on retry. Run keys are scoped to your account. Both API versions retain a key for 24 hours after acceptance, including across UTC midnight. Retries keep returning its original run during that window and while the run remains active. Once 24 hours have passed and the run has ended, reusing the key can start another billed run. Use a new key for new work. Valid keys contain 1–128 URL-safe characters: letters, numbers, _, ., :, or -.

Wait synchronously or poll

Add "sync": true for short, interactive tasks. StefanBrain holds the connection for up to about 90 seconds, counted from when it receives the request, and answers as soon as the run ends. If the run takes longer, the request returns the ordinary 202 response and continues in the background. Set your HTTP client’s timeout to 120 seconds so it receives that response. Poll the returned status URL every 3–10 seconds until the run is terminal. Polling does not count against rate limits. Use synchronous mode for short interactive requests. Use polling for long work, batch pipelines, or environments where holding a connection is fragile.

Follow progress events

The events endpoint returns turn phases, tool activity, and text sections. Page through events with the cursor returned as next_after:
Each page returns up to 200 events. Pass next_after as after. When a page is empty, next_after is null; keep your previous cursor. is_done is true on the page that contains the terminal event. The same endpoint supports server-sent events. Send this header:
Each SSE id is an event identifier. Heartbeats arrive approximately every 15 seconds, and the stream closes after the terminal event. Reconnect with Last-Event-ID or ?after= to resume. Cursor polling and SSE contain the same event data; choose one transport for each client.

Attach files

Send multipart/form-data when StefanBrain must read files with the message.
  • Put the JSON request body in a payload field.
  • Add every upload as a files field.
  • A run accepts up to 10 files.
  • Each file can be up to 100 MB.
  • Supported inputs include images, PDFs, common Office documents, spreadsheets, and text files.
  • Audio and video files are rejected. Host the media and put its public URL in message instead.
Use uploaded files parts for run attachments. Internal attachment identifiers and referenced document identifiers are not part of this public run request.

Request structured output

Add output_config.format to constrain the final answer to a JSON schema. The raw text remains in output; parsed JSON returns in structured_output. Structured output uses strict mode:
  1. The root schema must use "type": "object".
  2. Every object must set "additionalProperties": false.
  3. Every object must list all property names in required. To make a value optional, include null in its type.
An invalid strict-mode schema returns 400 invalid_output_config and identifies the failing path. structured_output is null when the run is unfinished or its final text is not valid JSON, including refusals and hard failures.

Model behavior

There is no model selector. If a request includes a model field, StefanBrain ignores it. Agent Runs execute the model that currently operates the StefanBrain product. See the generated REST reference for exact request and response schemas. See Errors and retries before adding retry logic.

Download produced files

A completed GET /api/developers/v1/runs/{run_id} response lists the files produced by that turn in artifacts. Match path to an outputs/... path in the answer, then download download.uri without an authorization header. The link is absolute and expires after 10 minutes. Read the run again to renew it. Credential revocation, file deletion, and removal of access are checked on download. Keep grant URLs out of logs and durable storage. Product jobs can finish after the assistant answers. Read the run again after a job completes to retrieve its file links.