# Overview

Brain exposes a **REST + JSON-RPC HTTP surface** and an **MCP server surface**. The same primitives are used by humans and agents. Only authentication differs.

### Base URLs

| Environment    | URL                            |
| -------------- | ------------------------------ |
| **Production** | `https://api.brain.fi`         |
| **Sandbox**    | `https://api.brain.fi/sandbox` |

### Authentication

| Caller     | Mechanism                                             |
| ---------- | ----------------------------------------------------- |
| **Humans** | OAuth / SSO (Auth0)                                   |
| **Agents** | SIWX (EIP-4361 over Base) + EIP-712 ScopeAttestations |

[**→ Authentication reference**](/api-reference/authentication.md)

### Representative endpoints

```
POST   /v1/sources                  // connect a financial source
POST   /v1/raw/ingest               // submit raw artifacts directly
GET    /v1/ledger/transactions      // structured records
POST   /v1/wiki/question            // NL query over memory
POST   /v1/policy                   // create or update a policy
POST   /v1/agents                   // register an external agent
POST   /v1/agents/{id}/propose      // propose an action
POST   /v1/actions/{id}/approve     // human approval
POST   /v1/actions/{id}/execute     // execute approved action
GET    /v1/audit/{id}               // audit trail with Merkle proof
```

### Endpoint reference

| Section                   | What's Covered                                         |
| ------------------------- | ------------------------------------------------------ |
| Authentication            | OAuth, SIWX, sessions, scopes                          |
| Sources and Raw Ingestion | Connect Plaid, banks, ERPs, wallets, files             |
| Ledger                    | Query transactions, balances, counterparties, invoices |
| Wiki                      | NL questions, entity browsing, semantic search         |
| Policy                    | Create, sign, simulate, evaluate, revoke               |
| Agents                    | Register, scope, list                                  |
| Actions                   | Propose, approve, execute                              |
| Audit                     | Events, Merkle proofs, exports                         |
| MCP Surface               | Tool list, namespacing, MCP-specific patterns          |

### Provenance on every response

Every response from Wiki, Policy, and Agent endpoints carries provenance.

| Field            | Description                                   |
| ---------------- | --------------------------------------------- |
| `ledger_refs`    | Ledger record IDs the answer depends on       |
| `raw_refs`       | Raw artifact hashes those records derive from |
| `policy_version` | Policy version evaluated, if any              |
| `audit_event_id` | Event ID under which the call was logged      |

### Versioning

The API is versioned in the URL path: `/v1/...`. Breaking changes always bump the version. Non-breaking additions (new endpoints, new fields) ship in place.

| Behaviour                             | Considered Breaking? |
| ------------------------------------- | -------------------- |
| Adding an endpoint                    | No                   |
| Adding a field to a response          | No                   |
| Adding an optional field to a request | No                   |
| Removing or renaming a field          | Yes                  |
| Changing default behaviour            | Yes                  |
| Changing an HTTP status code          | Yes                  |

### Rate limits

Rate limits apply per API key.

| Tier           | Requests / min | Burst  | Concurrent WebSockets |
| -------------- | -------------- | ------ | --------------------- |
| **Free**       | 60             | 100    | 5                     |
| **Developer**  | 600            | 1,000  | 25                    |
| **Production** | 6,000          | 10,000 | 250                   |
| **Enterprise** | Custom         | Custom | Custom                |

When rate-limited:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000
```

{% hint style="warning" %}
Always honour the `Retry-After` header. Aggressive retries against rate limits will result in temporary key suspension.
{% endhint %}

### Errors

All errors share a common shape.

```json
{
  "error": {
    "code":     "policy.denied",
    "message":  "Counterparty not approved",
    "details":  { "counterparty_id": "cp_x", "policy_version": 3 },
    "trace_id": "trc_8f3a92..."
  }
}
```

| Status | Meaning                                   |
| ------ | ----------------------------------------- |
| `400`  | Validation error                          |
| `401`  | Authentication failed                     |
| `403`  | Authenticated, but lacks scope            |
| `404`  | Not found                                 |
| `409`  | Conflict (e.g. duplicate registration)    |
| `422`  | Policy denied or escalation required      |
| `429`  | Rate limit exceeded                       |
| `500`  | Internal error (always logs a `trace_id`) |

### What's next

<table data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🪪 Authentication</strong></td><td>OAuth and SIWX in detail.</td><td><a href="/pages/0WFaizrTZls13BjYF116">/pages/0WFaizrTZls13BjYF116</a></td><td></td></tr><tr><td><strong>🌐 MCP Surface</strong></td><td>Same primitives, MCP shape.</td><td><a href="/pages/TQ2qB7I3AZOpEbqR4fZT">/pages/TQ2qB7I3AZOpEbqR4fZT</a></td><td></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.brain.fi/api-reference/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.