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

1. Create a key in Settings, Settings, API keys (paid tier required).
2. Read Authentication and API keys.
3. 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"