# API: overview

DURUM.ai exposes a **REST API** so you can read **your own data** (ad spend,
attribution, funnel, events, contacts, calls, journeys, creative needs) from your
own tools: a BI dashboard, a script, a data warehouse or an agency tool.

> **Warning: Paid tiers**
>
> The REST API and the MCP server are reserved for paid tiers (Starter, Growth,
> Scale). On the Discovery plan, every request returns `403 plan_free_no_api`. Keys
> are created in **Settings**, **Settings**, **API keys**.

To connect an AI assistant (Claude, ChatGPT or another MCP client), see
[MCP server](https://docs.durum.ai/en/developers/mcp).

## At a glance

| | |
|---|---|
| Base | `https://app.durum.ai/api/v1/` |
| Authentication | `Authorization: Bearer durum_sk_live_…` header |
| Reads | 30 `GET` routes, parameters in the query string |
| Writes | 9 `PUT` or `POST` routes, JSON body, `write:*` scopes granted explicitly |
| Response | `200` with `{ "data": … }`; errors with `{ "error": "…" }` |
| Rate limit | 600 requests per minute per key |
| Index | `GET https://app.durum.ai/api/v1/` (with the trailing slash) lists the routes and their scope |

> **Tip: The principle**
>
> You get **your results** (the numbers). DURUM's optimization engine, AI models,
> prompts, internal costs and margins are never exposed: those fields are stripped
> from every response before it is sent.

## What you can access

| Domain | Read scope | Examples |
|---|---|---|
| Dashboard | `read:dashboard` | aggregated KPIs, daily series, breakdowns by source, campaign, product, rep |
| Ads | `read:ads` | spend per ad and per campaign, ad rules and their run history |
| Attribution | `read:attribution` | multi-touch attribution per ad, capture health, report by source |
| Events | `read:events` | leads, applications, bookings, no-shows, sales, payments, cancellations |
| Sales | `read:sales` | sales summary, per-rep performance, sales cycle |
| Finance | `read:finance` | P&L and revenue (margins are not exposed) |
| Funnel | `read:funnel` | stages and conversion |
| Contacts | `read:contacts` | contacts, customers, purchases |
| Calls | `read:calls` | list of analyzed calls, transcript, recording |
| Journeys | `read:journeys` | customer journey with the UTM captured at each touchpoint |
| Creatives | `read:creatives` | pending creative needs |
| ICP | `read:icp` | your ideal customer criteria |
| Pixels | `read:capi` | your connected Meta pixels (never the tokens) |

The available writes (goals, sale rule, ICP criteria, ad rules, creative import,
creative-need acknowledgement) are detailed in the
[API reference](https://docs.durum.ai/en/developers/api-reference#writes).

## Security and isolation

- Each key is **bound to a single account**. The account is derived from the key
  server-side; you never send it and you can never read another client's data.
- Access is **granular**: a key only reaches the [scopes](https://docs.durum.ai/en/developers/authentication#scopes)
  it carries. Without the scope, the route answers `403`.
- **Read-only by default**: a key writes nothing unless it carries a `write:*`
  scope.
- Every authenticated request is **logged** (key, method, path, scope, response
  code, IP address).
- Tokens, secrets, model identifiers, costs and margins are **stripped from all
  responses**, at every nesting level.

> **Warning: Personal data (Law 25 / GDPR)**
>
> The API can return your prospects' data (emails, phone numbers, call transcripts
> and recordings). You are responsible for using it in compliance with applicable
> regulations.

## Getting started

1. Create a key in **Settings**, **Settings**, **API keys** (paid tier required).
2. Read [Authentication and API keys](https://docs.durum.ai/en/developers/authentication).
3. Browse the [API reference](https://docs.durum.ai/en/developers/api-reference) and try it:

```bash
curl "https://app.durum.ai/api/v1/dashboard/kpis?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer durum_sk_live_YOUR_KEY"
```

## Machine-readable resources

| Resource | Address |
|---|---|
| OpenAPI 3.1 specification | [`https://docs.durum.ai/openapi.json`](https://docs.durum.ai/openapi.json): every route with an `operationId`, typed parameters and response schemas, ready for LLM function calling |
| Route index (no key) | `GET https://app.durum.ai/api/v1/` |
| Tools for your key | `GET https://app.durum.ai/api/v1/tools` (key required) |
| MCP server | `https://app.durum.ai/mcp` (Streamable HTTP), manifest: [`/.well-known/mcp.json`](https://docs.durum.ai/.well-known/mcp.json) |
| Index for agents | [`/llms.txt`](https://docs.durum.ai/llms.txt); every page of these docs also exists in Markdown (append `.md` to the URL or send `Accept: text/markdown`) |

> **Info: Testing**
>
> There is no separate sandbox environment. To try the API safely: create a key with `read:*` scopes only (no write possible), and use the dry-run mode of ad rules, which computes without acting on the ad network.

---

Source: https://docs.durum.ai/en/developers/
