> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teamduo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API overview

> The small, deliberate REST surface an API key can reach.

TeamDuo's REST API is the web app's own backend, and most of it is **session-only by
design**. Connecting a database, changing exposure, managing team members, generating
documentation — all of it requires a signed-in browser session. An API key sent to any of
those routes is refused outright, regardless of what scopes it carries:

```json theme={null}
{ "error": "API keys cannot be used for this endpoint. Sign in to manage your account.", "code": "SCOPE_REQUIRED" }
```

That's not a bug to work around. `requireAuth` refuses API keys by default, and each route
has to opt in deliberately — the same rule this documentation states elsewhere: a route
that forgets to declare a scope stays session-only rather than falling open to every key.
The routes that connect a database or change what's exposed are exactly the ones that must
never open to an agent's key.

## What a key can actually call

Five endpoints, matching the same read-only surface the [MCP connector](/guides/mcp-clients)
uses:

| Endpoint                                      | Scope         |
| --------------------------------------------- | ------------- |
| `GET /users/me`                               | `profile`     |
| `GET /teams`                                  | `data:schema` |
| `GET /teams/{teamId}/datasources`             | `data:schema` |
| `GET /teams/{teamId}/datasources/{id}/schema` | `data:schema` |
| `POST /teams/{teamId}/datasources/{id}/query` | `data:read`   |

Full request and response shapes are in the reference pages in the sidebar.

<Note>
  If you're building an agent integration, prefer [MCP](/guides/mcp-clients) over calling
  these directly. It's the same data and the same rules, with tool descriptions written for
  a model to read and OAuth handling registration for you. The REST endpoints exist for
  scripts and services that want raw HTTP instead.
</Note>

## Authentication

```text theme={null}
Authorization: Bearer <your_api_key_or_access_token>
```

Create a key under **Settings → API keys** — see [API keys and scopes](/reference/api-keys)
for what each scope grants and how to think about them.

## Base URL

```text theme={null}
https://api.teamduo.ai
```

## Errors

Every error is `{ "error": string, "code"?: string }`. A `403` from a query names what was
blocked — an unexposed table, a disallowed MongoDB stage, a query over the cost limit —
because an agent or script that's told why can correct itself; one given a generic error
retries blind. See [Security model](/reference/security).

A `429` includes `retryAfter` in the body and a `Retry-After` header. Queries are budgeted
per team, not per caller — an MCP session and an API key on the same team share one budget.