Tagbreeze Create a key

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

RequestAnswer
GET /v1/sites?days=7Every site: health, events, purchases, leads, revenue, ad spend, ROAS.
GET /v1/sites/{id}/report?days=30&model=lastPer channel, campaign and ad: purchases, leads, revenue, spend, ROAS, cost per result, and what the ad platform claims.
GET /v1/sites/{id}/customers?days=180Customers, orders, revenue, value per customer and repeat rate, by first touch and by month of arrival.
GET /v1/sites/{id}/conversions?days=30&limit=100The 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_currencies and left out of the sum.
  • ROAS is null when 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 when utm_content carries 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