> ## 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.

# For agents and tooling

> Give coding agents machine-readable StefanBrain documentation, OpenAPI, and a grounded implementation brief.

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`](https://docs.stefanbrain.com/llms-full.txt) contains the published documentation as one Markdown document.
* [`https://docs.stefanbrain.com/llms.txt`](https://docs.stefanbrain.com/llms.txt) is a short index of the published documentation.
* [`https://stefanbrain.com/api/developers/v1/openapi`](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.

<Note>
  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.
</Note>

## Brief an implementation agent

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

```text theme={"system"}
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](/developers/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](/developers/quickstart), then read [Agent Runs](/developers/agent-runs) or [Tools and jobs](/developers/tools-and-jobs).

In TypeScript, install the [SDK](/developers/sdk). `@stefanbrain/sdk` ships an `AGENTS.md` quickstart that a coding agent can read from `node_modules`.

In a shell, install the [CLI](/developers/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](/developers/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.