# Brain API

> Run Obi's brain tools over plain HTTP and upload documents (PDF, Word, PowerPoint) for scripts, CLIs and apps that don't speak MCP.

The Brain API runs the same tools as MCP (see [Brain tools](https://outbind.ai/docs/tools)) over plain HTTPS, and takes real files for Obi to learn from. It's for scripts, command line tools and apps that don't speak MCP. If your app speaks MCP, use [MCP](https://outbind.ai/docs/connect) instead.

Base URL:

```
https://app.outbind.ai/api/v1/brain
```

## Authentication

Send a key or token in the `Authorization` header on every request:

```
Authorization: Bearer ob_your_key
```

- **Key from agent sign-up** (`ob_…`): what [agent sign-up](https://outbind.ai/docs/sign-up#an-ai-agent-signs-the-person-up) returns.
- **AI assistant key** (`ob_…`): the person makes one in [Settings, MCP](https://app.outbind.ai/settings/mcp) under **Use a key instead**. Pick **AI assistant, can draft and edit**. It's shown once.
- **Sign-in token** (`obt_…`): from the same OAuth sign-in MCP uses (PKCE, a localhost redirect is allowed for CLIs). See [Connect over MCP](https://outbind.ai/docs/connect#for-developers).

Keys in URLs, session cookies and browser requests from other sites are refused. The API is capped at **can draft and edit**, whatever the key allows: nothing here finds leads, enriches, sends or approves.

## Endpoints

| Method and path | What it does |
| --- | --- |
| `GET /` | The key's workspace, role, access and tool names. |
| `GET /tools` | The tools this key can run, described exactly like MCP's `tools/list`: `name`, `title`, `description`, `inputSchema`, `annotations`. |
| `POST /tools/{name}` | Runs one tool. The JSON body is its input (`{}` when it takes none). Answers `{ "result": … }`. |
| `GET /documents` | The documents Obi learned from: name, status, summary and facts. |
| `POST /documents` | Adds one file as multipart field `file`: PDF, Word, PowerPoint, text, Markdown or CSV, up to 10 MB. Owner or admin. Answers `202` while Obi reads it (about a minute), `200` if the same file was already there. |
| `DELETE /documents/{id}` | Removes a document and what Obi learned from it. |

## Examples

```
curl -H "Authorization: Bearer $OUTBIND_API_KEY" \
  https://app.outbind.ai/api/v1/brain/tools

curl -H "Authorization: Bearer $OUTBIND_API_KEY" \
  -H "content-type: application/json" \
  -d '{"prospect":{"email":"jane@acme.com","company":"Acme"}}' \
  https://app.outbind.ai/api/v1/brain/tools/write_email

curl -H "Authorization: Bearer $OUTBIND_API_KEY" \
  -F file=@deck.pdf \
  https://app.outbind.ai/api/v1/brain/documents
```

## Errors and limits

Errors look like `{ "error": { "code": "…", "message": "…", "fields": { … } } }`.

| Status | Meaning |
| --- | --- |
| `400` | The input failed the tool's check; `fields` says which. |
| `401` | No key, or the key was revoked. |
| `403` | The person's role can't do this. |
| `404` | No such tool for this key (a tool the key can't use answers the same). |
| `429` | Too many calls: wait and try again. |
| `503` | The Brain API is paused; MCP still works. |

Per key: 60 tool calls a minute and 60 changes an hour. Request bodies up to 320 KB (10 MB for a file). Every call is written to the workspace's audit log with what it did, never its input or output.