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.
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.
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 |
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.
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 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.
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
- Create a key in Settings, Settings, API keys (paid tier required).
- Read Authentication and API keys.
- Browse the API reference and try it:
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: 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 |
| Index for agents | /llms.txt; every page of these docs also exists in Markdown (append .md to the URL or send Accept: text/markdown) |
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.