For agents and tooling

Use machine-readable sources when an AI coding agent or API tool needs StefanBrain context. Do not make an agent scrape rendered HTML.

Machine-readable sources

https://docs.stefanbrain.com/llms-full.txt contains the published documentation as one Markdown document.
https://docs.stefanbrain.com/llms.txt is a short index of the published documentation.
https://stefanbrain.com/api/developers/v1/openapi is the OpenAPI 3.1 contract for SDK generation, request validation, and API tooling. It does not require authentication.
https://docs.stefanbrain.com/mcp is the read-only documentation MCP endpoint.
https://stefanbrain.com/api/developers/v1/mcp is the product MCP endpoint that exposes StefanBrain capabilities.

The OpenAPI specification is authoritative for endpoint and schema shape. These guides explain behavior, billing, lifecycle, and integration choices that a generated endpoint page cannot capture by itself.

Brief an implementation agent

Give the agent /llms-full.txt and the OpenAPI URL, then include the requirements relevant to the integration:

Implement this integration against the official StefanBrain Developer API.

Documentation: https://docs.stefanbrain.com/llms-full.txt
OpenAPI 3.1: https://stefanbrain.com/api/developers/v1/openapi

Requirements:
- Authenticate each REST request with Authorization: Bearer <key> or x-api-key.
- Keep the key server-side and out of committed files.
- A stefan_sk_ key on REST bills the API wallet. A stefan_oat_ OAuth token bills the plan pool unless the account has partner-specific terms.
- Start full agent work with POST /api/developers/v1/runs and a message.
- Use JSON, or multipart/form-data with a JSON payload field and repeated files fields.
- Do not attach audio or video files to a run. Host them and put the public URL in message.
- Do not send a model selector; runs use the StefanBrain product model.
- For short work, send sync: true and still handle 202 by polling status_url until status is completed, failed, or cancelled.
- Give a sync: true request a 120-second HTTP timeout.
- Send Idempotency-Key on every run start, so that retrying after a dropped connection or a gateway 502/504 returns the original run.
- A chat runs one turn at a time. Only `on_busy: "reject"` is supported. Busy chats are refused; poll the blocking run and retry after it finishes.
- An Idempotency-Key is 1-128 characters of A-Z, a-z, 0-9, _, ., :, or -. Runs, ask_stefanbrain, and every asynchronous submit tool except research_shortform honor it for the rest of the same UTC day. Keep the same chat, project, and session address when retrying.
- Read the final text from output and parsed structured JSON from structured_output.
- For direct tools, fetch the live catalog and use each input_schema and output_schema.
- Preserve chat identifiers for follow-up turns and job polling.
- Check is_error and error even when a tool or job request returns HTTP 200.
- Handle 429 and transient 5xx responses with backoff. Honor Retry-After.
- When an endpoint fails, returns the wrong thing, or lacks something you need, report it with POST /api/developers/v1/feedback. Send one report per problem, with the endpoint, error code, and run or chat id. Read the reply with GET /api/developers/v1/feedback/{feedback_id}.
- Current OpenAPI 3.1 contract: https://stefanbrain.com/api/developers/v1/openapi

Choose the richest integration available

If the host supports MCP, connect the StefanBrain product MCP. The agent receives StefanBrain’s tools directly instead of generating HTTP calls from the REST schema. Use REST when you are building an automated application, pipeline, or service. Start with Quickstart, then read Agent Runs or Tools and jobs. In TypeScript, install the SDK. @stefanbrain/sdk ships an AGENTS.md quickstart that a coding agent can read from node_modules. In a shell, install the CLI. @stefanbrain/cli ships an AGENTS.md quickstart and an installable Agent Skill in SKILL.md. sb prints JSON only on stdout and uses stable exit codes, so an agent can parse each result and branch on failures.

Report where the API gets in the way

Tell your agent to send feedback when the API gets in its way: a failed call, an unclear error, wrong docs, or a missing capability. It can send a report with POST /api/developers/v1/feedback, the MCP send_feedback tool, client.feedback.send in SDK 0.5.0, or sb feedback send in CLI 0.5.0. The StefanBrain team reads every report and replies, and the reply reaches the agent. Reports are free. See Agent feedback.

Implementation checks

Treat OpenAPI response schemas as additive. Tolerate fields you do not recognize.
Store run_id for traceability.
Reuse chat for follow-up turns in the same conversation.
Use a separate chat or session label for independent parallel work.
Follow lifecycle URLs returned by runs and jobs instead of reconstructing them.
Poll with the same project and session used by a submit call. Job lookups are chat-scoped.
Use POST /api/developers/v1/files to stage local files and pass the returned ids to ask_stefanbrain.
For strict structured output, set additionalProperties: false on every object and list every property in required.
When structured_output is null, read output and last_error before deciding how to recover.
Check is_error in successful direct-tool responses.

Get started

Build with StefanBrain

Operate safely

REST API reference

For agents and tooling

Machine-readable sources

Brief an implementation agent

Choose the richest integration available

Report where the API gets in the way

Implementation checks

​Machine-readable sources

​Brief an implementation agent

​Choose the richest integration available

​Report where the API gets in the way

​Implementation checks

Machine-readable sources

Brief an implementation agent

Choose the richest integration available

Report where the API gets in the way

Implementation checks