# API and MCP integration

<!-- machine twin: /api/legal/api-and-mcp?format=md -->
<!-- version: 13529e1a07ad -->
# API and MCP integration

Automate DejaBars from your own code or from an AI agent.

## Create an API key

1. Sign in and open your account page.
2. Create a key and give it a label so you can recognise it later.
3. Copy the key immediately — it is shown **once**; we store only a hash of it.
4. Send it on every request in the `X-API-Key` header.

You can list your keys (labels and last use) and revoke any of them at any time. Revoking is
immediate.

## Base URL and versioning

The API is available at `https://dejabars.com/v1`. Every route is also served without the prefix, but new
integrations should pin `/v1`.

```
curl -H "X-API-Key: $DEJABARS_KEY" https://dejabars.com/v1/coins
```

## Useful endpoints

| Method | Route | Purpose |
|---|---|---|
| `GET` | `/v1/coins` | The tracked coins and their stats |
| `GET` | `/v1/klines` | OHLC candles for a symbol and timeframe |
| `POST` | `/v1/search-task` | Start a pattern search |
| `GET` | `/v1/task-stream/{task_id}` | Server-sent progress until the search completes |
| `GET` | `/v1/task-result/{task_id}` | The stored summary of a finished search |
| `GET` | `/v1/task-result/{task_id}/symbol/{symbol}` | Every match for one coin |
| `GET` | `/v1/auth/api-keys` | List your keys |

Interactive documentation, generated from the running service, is served by the API itself at
`/docs` on the API host.

## The search flow

1. `POST /v1/search-task` with your pattern points, timeframe, algorithm and filters. The response
   contains a `task_id` and a queue position.
2. Follow `GET /v1/task-stream/{task_id}` for progress, or poll `GET /v1/task-result/{task_id}`.
3. Read a single coin's matches with the symbol route when you only need one.

Searches are queued and run one at a time per account, so a burst of submissions waits its turn
instead of running in parallel. Only the searches you actually start are charged.

## MCP (Model Context Protocol)

`backend/mcp_server.py` exposes the same API over MCP so an agent can drive searches directly. Set
`MCP_API_URL` to your API base and `MCP_API_KEY` to a key you created above; the server sends it as
`X-API-Key`.

## Rules

- Stay inside the documented rate limits; do not build a bulk downloader or mirror the dataset.
- One key per integration, and revoke keys you no longer use.
- Everything in the [Acceptable Use Policy](/docs/acceptable-use-policy) applies to programmatic
  access.