API and agents
Set up and read TagSentry from a script or a coding agent: keys, device sign-in, the setup calls, webhooks and limits.
The short answer
Setup, the banner, consent records and tag events are all API calls. A coding agent can get a key once you approve it in the browser. It can then create the site, read the one line to install and check what's left. Tag Manager is read-only through the API.
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_…(ortsk_test_…). A member of the account makes keys in the dashboard. Atsk_test_key is a real key on real data; the prefix only records which deployment minted it. - Scopes are listed on each key, and each one has to be granted: a key that reads and creates sites needs both
sites:readandsites:write. Keys can't make other keys.
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:
POST /device-authorizationswith the scopes it needs. The answer has auserCodeand averificationUrl.- The person opens the link, signs in (or signs up) and approves.
- The script polls
POST /device-authorizations/tokenevery few seconds until it getsstatus: "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 stay for their 24 months |
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 and no visitor dataruleset.publishedscan.completedping, 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; we retry failures 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'strue, you aren't looking at the whole answer. - Every error has a
code, amessageand arequestId. Quote therequestIdif you write to us. - Tag Manager is read-only here. No call writes to a customer's container. A person approves changes in the dashboard.
MCP server
The TagSentry MCP server is live at https://app.tagsentry.ai/api/mcp (Streamable HTTP). Connect it by URL. You sign in with your TagSentry account, pick a business and press Allow. It signs in with OAuth rather than an API key.
| 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,list_brands,get_check_results. - Do:
create_site,start_scan,check_verification,create_review_link(a link a client opens with no login; it lasts 14 days, and approving it publishes nothing). - Only after you agree:
update_banner,apply_brandandarchive_sitedo nothing until they're called again withconfirm: true.
Billing, Tag Manager changes and consent exports stay in the dashboard. 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 statuschecks the domain and says what the site needs next.tagsentry undoputs back what the lastinitchanged.--jsongives one JSON object per line, for agents and CI.