API and MCP server
Read your reports from your own tools, or ask an assistant about them. Everything here is read-only.
Version 1 · 19 November 2026
Your key
Create a key in the console, under Account › API and assistants. It is shown once. Send it with every request:
Authorization: Bearer tb_…
A key reads every site of its account and changes nothing. Delete it in the console to switch it off at once. Limit: 120 requests per minute per key; beyond that the answer is 429.
Periods and credit
days is one of 7, 30, 90, 180 or 365. model says which visit gets the credit for a sale: last (the default), the last channel the visitor came through, or first, the one that brought them the first time.
Endpoints
| Request | Answer |
|---|---|
GET /v1/sites?days=7 | Every site: health, events, purchases, leads, revenue, ad spend, ROAS. |
GET /v1/sites/{id}/report?days=30&model=last | Per channel, campaign and ad: purchases, leads, revenue, spend, ROAS, cost per result, and what the ad platform claims. |
GET /v1/sites/{id}/customers?days=180 | Customers, orders, revenue, value per customer and repeat rate, by first touch and by month of arrival. |
GET /v1/sites/{id}/conversions?days=30&limit=100 | The latest conversions, each with its value and its first and last touch. limit goes up to 500. |
Example
curl https://tagbreeze.com/v1/sites/SITE_ID/report?days=30 \ -H "Authorization: Bearer tb_…"
{
"site": { "id": "…", "name": "My shop", "host": "myshop.com" },
"days": 30, "model": "last", "currency": "MAD",
"totals": { "purchases": 42, "leads": 9, "revenue": 18450, "spend": 6200, "roas": 2.98, "cpa": 121.57 },
"channels": [
{ "key": "meta", "label": "Meta Ads", "purchases": 25, "revenue": 11300, "spend": 4100, "roas": 2.76,
"platform_conversions": 31, "campaigns": [ { "id": "5001", "name": "Prospecting", "ads": [ … ] } ] }
]
}
Reading the numbers
- Revenue is counted in one currency, the one most purchases use. Purchases in another currency are listed under
notes.other_currenciesand left out of the sum. - ROAS is
nullwhen there is no spend, or when spend and revenue are in different currencies. - platform_conversions is what Meta or Google Ads report for the same days. It is shown beside what the tag recorded, never mixed with it.
- A sale lands on a campaign when the link of the ad carries the campaign ID or name in
utm_campaign, and on an ad whenutm_contentcarries the ad ID. Otherwise it stays on the channel.
Errors
401 no key or unknown key. 402 the plan of the account has ended. 404 unknown address, or a site that is not in this account. 405 anything but GET. 429 too many requests.
MCP server, for assistants
The same data, for assistants that speak the Model Context Protocol: Claude, ChatGPT, Codex, Cursor and others. The server lives at:
https://tagbreeze.com/mcp
Four tools, all read-only: list_sites, get_ad_report, get_customer_value and list_conversions. Then ask in plain words, for example: “Which campaign had the best ROAS on my shop over the last 30 days?”
Two ways to connect
Sign in (recommended). Give the assistant the address above and nothing else. It sends you to Tagbreeze, you sign in and press Allow, and you are back in the assistant. No key to copy. You can disconnect an assistant at any time in the console, under Account.
With a key. For scripts and for tools that take a header: send an API key as Authorization: Bearer tb_…, exactly as for the API.
Claude (web and desktop apps)
Open Settings, then Connectors, choose to add a custom connector, and paste the address. Claude opens the Tagbreeze sign-in page; press Allow.
Claude Code
claude mcp add --transport http tagbreeze https://tagbreeze.com/mcp
Then run /mcp inside Claude Code, pick tagbreeze and sign in. With a key instead:
claude mcp add --transport http tagbreeze https://tagbreeze.com/mcp \ --header "Authorization: Bearer tb_…"
ChatGPT
Where your plan allows custom connectors: open Settings, then Connectors, create a connector, and paste the address. ChatGPT opens the Tagbreeze sign-in page; press Allow.
Codex
codex mcp add tagbreeze --url https://tagbreeze.com/mcp codex mcp login tagbreeze
With a key instead, in ~/.codex/config.toml, the key being in an environment variable:
[mcp_servers.tagbreeze] url = "https://tagbreeze.com/mcp" bearer_token_env_var = "TAGBREEZE_API_KEY"
Cursor
In .cursor/mcp.json (or the global one), then sign in when Cursor asks:
{ "mcpServers": { "tagbreeze": { "url": "https://tagbreeze.com/mcp" } } }
For developers of assistants
The server uses the streamable HTTP transport (POST, JSON answers). Without a token it answers 401 with a WWW-Authenticate header that names its protected-resource metadata. The authorisation server supports metadata discovery, dynamic client registration for public clients, the authorisation-code flow with PKCE (S256, required) and rotating refresh tokens. Access tokens last one hour.
https://tagbreeze.com/.well-known/oauth-protected-resource https://tagbreeze.com/.well-known/oauth-authorization-server