API and agents

The basics

• Base URL: https://app.tagsentry.ai/api/v1
• Spec: /api/v1/openapi.json, with a rendered reference at app.tagsentry.ai/docs/api
• Auth: Authorization: Bearer tsk_live_… (or tsk_test_…). Keys are made in the dashboard by a member of the account. A tsk_test_ key is a real key on real data; the prefix only records which deployment minted it.
• Scopes are listed on each key and never implied: a key that reads and creates sites needs both sites:read and sites:write. A key can never make another key.

Using Claude Code, Cursor or another coding agent? Point it at tagsentry.ai/SKILL.md, a step-by-step brief it can follow.

Getting a key without the dashboard

A script with no key can ask for one, and a person approves it in the browser:

1. POST /device-authorizations with the scopes it needs. The answer has a userCode and a verificationUrl.
2. The person opens the link, signs in (or signs up) and approves.
3. The script polls POST /device-authorizations/token every few seconds until it gets status: "issued" and the key.

These two calls are the only ones that take no key.

Setting up a site

Call	What it does
POST /sites	Create a site: domain, displayName, region (EU or US, fixed for life)
GET /sites/{id}/install	The one line to put first in <head>, the inline snippet, the same pieces laid out for frameworks, and a csp field listing exactly what your Content Security Policy must allow
GET /sites/{id}/verification	How the domain is proven (method, methods). Pasting the tag usually proves it with no call: we check the homepage every 10 minutes for the first hour, then hourly
POST /sites/{id}/verification/checks	Check now
POST /sites/{id}/scans	Start a scan
GET /sites/{id}/scans/latest	Whether a scan has finished
GET /sites/{id}/status	What's done and what's left, with the next thing to do
POST /sites/{id}/archive	Close a site. Idempotent. A site on a paid plan needs a key an owner minted. Consent records are never deleted

Other calls read consent records and exports, tag events, trackers, the connected Tag Manager inventory and billing, and change the banner's design, wording and links.

Webhooks

Add endpoints per business on the API keys page. Events:

• consent.recorded: batched, at most one POST a minute per site, with counts and record ids, never visitor data
• ruleset.published
• scan.completed
• ping, sent by Send test

Each POST carries X-TagSentry-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of t and the raw body joined by a full stop, keyed with the endpoint's secret. Refuse a t more than 5 minutes from your clock. X-TagSentry-Delivery stays the same across retries, so dedupe on it. Answer 2xx within 10 seconds; failures are retried with backoff.

Limits and honest answers

• Rate limits are per key and per account, per minute, plus banner writes per site. A 429 names the budget and carries Retry-After.
• Every list response has truncated. When it's true, you aren't looking at the whole answer.
• Every error has a code, a message and a requestId. Quote the requestId if you write to us.
• Tag Manager is read-only here. No call writes to a customer's container. Changes are approved by a person in the dashboard.

MCP server

The TagSentry MCP server is live at https://app.tagsentry.ai/api/mcp (Streamable HTTP). It isn't in the Claude or ChatGPT directories yet, so connect by URL. You sign in with your TagSentry account, pick a business and press Allow. API keys don't work here; it's OAuth sign-in only.

Client	How to connect
Claude Code	claude mcp add --transport http tagsentry https://app.tagsentry.ai/api/mcp, then run /mcp to sign in
Claude	Settings, Connectors, Add custom connector, paste the URL. Needs a paid Claude plan
Cursor	In ~/.cursor/mcp.json: {"mcpServers":{"tagsentry":{"url":"https://app.tagsentry.ai/api/mcp"}}}
VS Code	Add an HTTP MCP server with the URL
ChatGPT	Developer mode for now: Settings, Apps, Create, paste the URL

What it can do:

• Read: list_sites, get_account, get_site_status, get_install_snippet, get_install_instructions, get_verification, get_scan_status, get_tag_events, get_consent_records, list_trackers.
• Do: create_site, start_scan, check_verification.
• Only after you agree: update_banner and archive_site do nothing until they're called again with confirm: true.

Billing, Tag Manager changes and consent exports are never available over MCP. Disconnect an assistant in Settings, API keys, Connected apps.

Command line

Run this in your project folder:

npx @tagsentry/cli

It signs you in (or creates your account) in the browser, detects your framework (Next.js, Remix, Astro, Vite, SvelteKit, Nuxt, plain HTML and more), adds the line in the right place, and can add the MCP server to Claude Code, Cursor, VS Code, Claude Desktop or Windsurf. For a site builder (WordPress, Shopify, Webflow, Squarespace, Wix) it gives you the line and where to paste it.

• tagsentry status checks the domain and says what the site needs next.
• tagsentry undo puts back what the last init changed.
• --json gives one JSON object per line, for agents and CI.