{ "openapi": "3.1.0", "info": { "title": "TagSentry API", "version": "2026-08-26", "summary": "Set up consent and event monitoring without opening the dashboard.", "description": "Everything after sign-up is meant to be reachable by a script or an agent.\n\n**Authentication.** A bearer API key: `Authorization: Bearer tsk_live_...` (or `tsk_test_...`). Keys are minted from the dashboard by a member of the account, or issued to a terminal through the device authorization grant below, and carry an explicit, non-implied list of scopes. A key can never mint another key.\n\n**Test keys.** The prefix names the deployment that minted the key, and nothing reads it after that. `tsk_live_`: Minted by a production or staging deployment, app.tagsentry.ai included. The prefix a secret scanner should match. `tsk_test_`: Minted by a development or self-hosted deployment without a production APP_ENV. Not a sandbox: it has the same scopes and reaches the same real data as a live key, on the deployment that minted it. No other deployment knows it. There is no sandbox mode: to test without touching a real site, create a throwaway site and archive it afterwards.\n\n**The one exception.** `POST /device-authorizations` and `POST /device-authorizations/token` take no credential -- they are how something with no key gets one, with a human approving in a browser. Every other operation on this surface requires a key.\n\n**Tenancy.** The account a request acts for comes from the key and from nowhere else -- never from a path, query or body. A site id belonging to another account resolves to 404.\n\n**Regions.** A site is created in EU or US and its consent records and tag events live there. The region is a property of the site, read from our index; it is never accepted from the request. Responses that read regional data carry `X-TagSentry-Region`.\n\n**Truncation.** Every list response carries `truncated`. When it is true you are not looking at the whole answer. Treat it as an error condition for anything that has to be complete.\n\n**Rate limits.** Per key and per account, per minute; banner writes also per site. A 429 names which budget and carries `Retry-After`. If we cannot check a budget we refuse rather than guess.\n\n**Strict Content-Security-Policy.** `GET /sites/{siteId}/install` returns `csp`: the origins, the hash of the one-line tag's onerror handler (it needs `'unsafe-hashes'`), and this site's inline-snippet hashes.\n\n**Tag Manager is read only here.** No operation in this version writes to a customer's container; changes are approved by a person in the dashboard.\n\n**Webhooks.** Added per business in the dashboard (API keys page) for `consent.recorded` (batched, at most one POST a minute per site, counts and record ids, never visitor data), `ruleset.published` and `scan.completed`, plus `ping` from Send test. Each POST is signed: `X-TagSentry-Signature: t=,v1=` with the endpoint's secret. Refuse a `t` more than 5 minutes old. `X-TagSentry-Delivery` is stable across retries; dedupe on it. The `webhooks` section of this document has each body and a verification snippet.", "contact": { "name": "TagSentry", "url": "https://tagsentry.ai" } }, "servers": [ { "url": "/api/v1", "description": "This deployment." } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "tsk_live_… / tsk_test_…", "description": "An API key. Scopes are additive and never implied: a key that needs to both read and create sites carries `sites:read` AND `sites:write`.\n\n- `account:read` — Read which account this key belongs to: its id, its name and whether a person has confirmed that name. Carries no region (each site names its own when it is created), no billing and no member list.\n- `sites:read` — List sites and read their setup state.\n- `sites:write` — Create sites and archive them.\n- `scans:write` — Start a scan of a site.\n- `trackers:read` — Read the detected tracker inventory and its classification.\n- `monitoring:read` — Read tag events, event-name summaries and the tag flow.\n- `consent:read` — Read consent decisions and their rates.\n- `consent:export` — Download the proof-of-consent export.\n- `install:read` — Read the install snippet, the site key and the delivery origin.\n- `banner:write` — Change and publish the consent banner and its ruleset.\n- `gtm:read` — Read the connected Tag Manager container and its tag inventory.\n- `gtm:write` — Stage and publish a consent version into the customer's Tag Manager container. Additionally requires a verified domain and a live step-up OAuth grant that only a human can create. No API operation uses it yet.\n- `billing:read` — Read whether each site is Free or Pro in each product, its usage and payment state. Owner-only." } }, "schemas": { "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "domain_not_verified", "not_found", "invalid_request", "conflict", "rate_limited", "not_implemented", "internal" ] }, "message": { "type": "string" }, "detail": {}, "requestId": { "type": "string" } }, "required": [ "code", "message", "requestId" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "description": "Every non-2xx response from this API has this shape." } } }, "tags": [ { "name": "Getting a key", "description": "How a process with no credential gets one: it shows a human a code, the human approves it in a browser, and the process polls. Start here if you are a CLI, an agent, or anything else running where nobody can paste a secret in." }, { "name": "Sites", "description": "Sites, and everything measured on one." }, { "name": "Account", "description": "The account this key belongs to." }, { "name": "Webhooks", "description": "What we POST to your endpoints, and how to verify it came from us." } ], "paths": { "/sites": { "get": { "operationId": "listSites", "summary": "List sites", "description": "Every site on the account this key belongs to. Archived sites are excluded unless you ask for them.", "tags": [ "Sites" ], "security": [ { "apiKey": [ "sites:read" ] } ], "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "description": "Include archived sites. Defaults to false.", "schema": { "description": "Include archived sites. Defaults to false.", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "List sites", "headers": { "X-Request-Id": { "description": "Echoed in the body of any error. Quote it when reporting a problem.", "schema": { "type": "string" } }, "X-TagSentry-Region": { "description": "Which regional database served this response, when it read regional data. A site's region is fixed at creation and is never taken from the request.", "schema": { "type": "string", "enum": [ "EU", "US" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The site's id. This is what every /v1/sites/{siteId} path takes." }, "accountId": { "type": "string" }, "domain": { "type": "string" }, "displayName": { "type": "string" }, "region": { "type": "string", "enum": [ "EU", "US" ], "description": "Where this site's consent records and tag events are stored. Fixed at creation and never editable -- data residency is not a setting you can flip." }, "status": { "type": "string", "enum": [ "pending", "active", "archived" ] }, "archivedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp, UTC." }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp, UTC." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp, UTC." } }, "required": [ "id", "accountId", "domain", "displayName", "region", "status", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The row cap applied to the underlying read." }, "truncated": { "type": "boolean", "description": "True when the read came back at its cap. When true, this page is NOT the whole answer -- narrow the window. An account's site list has no read cap -- `truncated` is always false here, and is present so the envelope's shape never varies by endpoint." }, "truncationHint": { "type": "string" } }, "required": [ "data", "limit", "truncated" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired API key. These are deliberately indistinguishable in the response -- distinguishing them would confirm to a caller that a token was once real.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The key authenticated but does not carry the scope(s) this operation requires, or (`domain_not_verified`) the site's domain is not verified, so its consent records are not released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something failed on our side. The requestId in the body is what to quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "operationId": "createSite", "summary": "Create a site", "description": "Adds a site to this account. The domain is not checked for ownership here and the site is usable immediately -- verification is a separate state that gates acting outward on the domain's behalf, never the site's existence. `region` is fixed at creation and can never be changed: it decides where this site's consent records and tag events are stored.", "tags": [ "Sites" ], "security": [ { "apiKey": [ "sites:write" ] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "displayName": { "type": "string", "minLength": 1 }, "region": { "type": "string", "enum": [ "EU", "US" ] } }, "required": [ "domain", "displayName", "region" ] } } } }, "responses": { "201": { "description": "Create a site", "headers": { "X-Request-Id": { "description": "Echoed in the body of any error. Quote it when reporting a problem.", "schema": { "type": "string" } }, "X-TagSentry-Region": { "description": "Which regional database served this response, when it read regional data. A site's region is fixed at creation and is never taken from the request.", "schema": { "type": "string", "enum": [ "EU", "US" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The site's id. This is what every /v1/sites/{siteId} path takes." }, "accountId": { "type": "string" }, "domain": { "type": "string" }, "displayName": { "type": "string" }, "region": { "type": "string", "enum": [ "EU", "US" ], "description": "Where this site's consent records and tag events are stored. Fixed at creation and never editable -- data residency is not a setting you can flip." }, "status": { "type": "string", "enum": [ "pending", "active", "archived" ] }, "archivedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp, UTC." }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp, UTC." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp, UTC." } }, "required": [ "id", "accountId", "domain", "displayName", "region", "status", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "The request did not validate against this operation's schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired API key. These are deliberately indistinguishable in the response -- distinguishing them would confirm to a caller that a token was once real.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The key authenticated but does not carry the scope(s) this operation requires, or (`domain_not_verified`) the site's domain is not verified, so its consent records are not released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The request conflicts with existing state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something failed on our side. The requestId in the body is what to quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/sites/{siteId}/archive": { "post": { "operationId": "archiveSite", "summary": "Archive a site", "description": "Takes a site out of the account: it leaves the site list, its banner stops being served, and its per-site billing line is released. The same archive the dashboard's Remove this site makes. To finish undoing an install, take the code off your pages too: until you do, it keeps setting denied Consent Mode defaults and shows no banner.\n\nNOTHING IS DELETED. The site's consent records, tag events and configuration stay in its region for their retention period, because a consent record is the legal proof of what a visitor chose. `GET /sites?includeArchived=true` still lists it.\n\nIDEMPOTENT. Archiving an archived site answers 200 with the same body and changes nothing.\n\nA site with a paid product can be archived only by a key an account OWNER minted, because it changes the bill: the dashboard's rule, read from the minter's current role. A member's key gets 403 for it and may archive a site that pays for nothing.", "tags": [ "Sites" ], "security": [ { "apiKey": [ "sites:write" ] } ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "description": "The site id, from GET /v1/sites.", "schema": { "type": "string", "description": "The site id, from GET /v1/sites." } } ], "responses": { "200": { "description": "Archive a site", "headers": { "X-Request-Id": { "description": "Echoed in the body of any error. Quote it when reporting a problem.", "schema": { "type": "string" } }, "X-TagSentry-Region": { "description": "Which regional database served this response, when it read regional data. A site's region is fixed at creation and is never taken from the request.", "schema": { "type": "string", "enum": [ "EU", "US" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The site's id. This is what every /v1/sites/{siteId} path takes." }, "accountId": { "type": "string" }, "domain": { "type": "string" }, "displayName": { "type": "string" }, "region": { "type": "string", "enum": [ "EU", "US" ], "description": "Where this site's consent records and tag events are stored. Fixed at creation and never editable -- data residency is not a setting you can flip." }, "status": { "type": "string", "enum": [ "pending", "active", "archived" ] }, "archivedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp, UTC." }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp, UTC." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp, UTC." } }, "required": [ "id", "accountId", "domain", "displayName", "region", "status", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired API key. These are deliberately indistinguishable in the response -- distinguishing them would confirm to a caller that a token was once real.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The key authenticated but does not carry the scope(s) this operation requires, or (`domain_not_verified`) the site's domain is not verified, so its consent records are not released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "No such resource on this account. A site id belonging to a DIFFERENT account answers 404, never 403 -- a 403 would confirm the id exists somewhere.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something failed on our side. The requestId in the body is what to quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/sites/{siteId}/tag-events": { "get": { "operationId": "listTagEvents", "summary": "Read tag events", "description": "What actually fired on this site, newest first: page views, the events that occurred on them, the tags that ran and the requests those tags sent. Served from the site's own region -- see the X-TagSentry-Region response header.\n\nThis is a time WINDOW, not a paged list. If `truncated` is true the window was too wide and you are NOT looking at the whole answer; narrow `from`/`to`.\n\nZero events does not mean the snippet is not installed. Monitoring runs only after a consent decision that grants the category it rides on, so a correct install on a site whose visitors reject analytics reports zero forever, correctly. The only honest reading of zero is \"we have not heard from it yet\".", "tags": [ "Sites" ], "security": [ { "apiKey": [ "monitoring:read" ] } ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "description": "The site id, from GET /v1/sites.", "schema": { "type": "string", "description": "The site id, from GET /v1/sites." } }, { "name": "from", "in": "query", "required": false, "description": "ISO-8601. Inclusive lower bound on receivedAt.", "schema": { "description": "ISO-8601. Inclusive lower bound on receivedAt.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "ISO-8601. Inclusive upper bound on receivedAt.", "schema": { "description": "ISO-8601. Inclusive upper bound on receivedAt.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Row cap. Capped by the service's own ceiling.", "schema": { "description": "Row cap. Capped by the service's own ceiling.", "type": "string" } }, { "name": "batchId", "in": "query", "required": false, "description": "One page view's rows.", "schema": { "description": "One page view's rows.", "type": "string" } } ], "responses": { "200": { "description": "Read tag events", "headers": { "X-Request-Id": { "description": "Echoed in the body of any error. Quote it when reporting a problem.", "schema": { "type": "string" } }, "X-TagSentry-Region": { "description": "Which regional database served this response, when it read regional data. A site's region is fixed at creation and is never taken from the request.", "schema": { "type": "string", "enum": [ "EU", "US" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "siteId": { "type": "string" }, "batchId": { "type": "string", "description": "One page view. Rows sharing a batchId happened on the same page." }, "seq": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Order within the batch. Seq 0 is always the batch row." }, "kind": { "type": "string", "description": "batch | tag | event | request" }, "receivedAt": { "type": "string", "description": "Our clock. The only orderable time here -- a client's is never trusted." }, "pageMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "subjectId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present on the batch row only. Links the page view to the consent decision that permitted it." }, "containerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tagId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "executionMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "eventName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ordinal": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "host": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "initiatorType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paramNames": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "occurrences": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "transferBytes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "buffered": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "id", "siteId", "batchId", "seq", "kind", "receivedAt", "pageMs", "subjectId", "containerId", "tagId", "status", "executionMs", "eventName", "ordinal", "host", "origin", "path", "initiatorType", "paramNames", "occurrences", "transferBytes", "durationMs", "buffered", "truncated" ], "additionalProperties": false } }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The row cap applied to the underlying read." }, "truncated": { "type": "boolean", "description": "True when the read came back at its cap. When true, this page is NOT the whole answer -- narrow the window. Tag events are a time window, not a paged list." }, "truncationHint": { "type": "string" } }, "required": [ "data", "limit", "truncated" ], "additionalProperties": false } } } }, "400": { "description": "The request did not validate against this operation's schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired API key. These are deliberately indistinguishable in the response -- distinguishing them would confirm to a caller that a token was once real.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The key authenticated but does not carry the scope(s) this operation requires, or (`domain_not_verified`) the site's domain is not verified, so its consent records are not released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "No such resource on this account. A site id belonging to a DIFFERENT account answers 404, never 403 -- a 403 would confirm the id exists somewhere.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something failed on our side. The requestId in the body is what to quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/sites/{siteId}/consent-records": { "get": { "operationId": "listConsentRecords", "summary": "Read consent decisions", "description": "This site's consent records, oldest first. Served from the site's own region.\n\nThese are the legal record of what each visitor was shown and what they chose. They are never edited and never deleted inside their retention period.\n\nIf `truncated` is true this is a PARTIAL answer -- narrow `from`/`to` and page through by time. Do not treat a truncated response as a complete history; for a regulator-facing artifact use the export endpoint, not this one.\n\nOnly for a site whose domain is verified: otherwise the answer is 403 `domain_not_verified`, and verifying the domain is the fix.", "tags": [ "Sites" ], "security": [ { "apiKey": [ "consent:read" ] } ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "description": "The site id, from GET /v1/sites.", "schema": { "type": "string", "description": "The site id, from GET /v1/sites." } }, { "name": "from", "in": "query", "required": false, "description": "ISO-8601. Inclusive lower bound on receivedAt.", "schema": { "description": "ISO-8601. Inclusive lower bound on receivedAt.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "ISO-8601. Inclusive upper bound on receivedAt.", "schema": { "description": "ISO-8601. Inclusive upper bound on receivedAt.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Row cap. Capped by the service's own ceiling.", "schema": { "description": "Row cap. Capped by the service's own ceiling.", "type": "string" } }, { "name": "subjectId", "in": "query", "required": false, "description": "One visitor's decision history.", "schema": { "description": "One visitor's decision history.", "type": "string" } } ], "responses": { "200": { "description": "Read consent decisions", "headers": { "X-Request-Id": { "description": "Echoed in the body of any error. Quote it when reporting a problem.", "schema": { "type": "string" } }, "X-TagSentry-Region": { "description": "Which regional database served this response, when it read regional data. A site's region is fixed at creation and is never taken from the request.", "schema": { "type": "string", "enum": [ "EU", "US" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "recordVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "id": { "type": "string", "description": "Deterministic and derived, not random -- the beacon may retry, and the legal record must not double-count." }, "subjectId": { "type": "string" }, "siteId": { "type": "string" }, "rulesetIntegrity": { "type": "string", "description": "Ties the decision to the exact banner configuration that was shown." }, "jurisdiction": { "type": "string" }, "jurisdictionReason": { "type": "string", "description": "How we placed the visitor. A no_signal fallback is a weaker claim than a determination, and this says which it was." }, "method": { "type": "string" }, "decidedAt": { "type": "string", "description": "From the visitor's device. A CLAIM." }, "receivedAt": { "type": "string", "description": "Stamped by us. Authoritative for ordering and retention." }, "granted": { "type": "array", "items": { "type": "string" } }, "denied": { "type": "array", "items": { "type": "string" } }, "signals": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "The Consent Mode v2 signals actually applied." }, "shown": { "description": "What banner the visitor was shown." } }, "required": [ "recordVersion", "id", "subjectId", "siteId", "rulesetIntegrity", "jurisdiction", "jurisdictionReason", "method", "decidedAt", "receivedAt", "granted", "denied", "signals", "shown" ], "additionalProperties": false } }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The row cap applied to the underlying read." }, "truncated": { "type": "boolean", "description": "True when the read came back at its cap. When true, this page is NOT the whole answer -- narrow the window. Consent records are returned oldest-first. Narrow the window with `from`/`to`." }, "truncationHint": { "type": "string" } }, "required": [ "data", "limit", "truncated" ], "additionalProperties": false } } } }, "400": { "description": "The request did not validate against this operation's schema.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired API key. These are deliberately indistinguishable in the response -- distinguishing them would confirm to a caller that a token was once real.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The key authenticated but does not carry the scope(s) this operation requires, or (`domain_not_verified`) the site's domain is not verified, so its consent records are not released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "No such resource on this account. A site id belonging to a DIFFERENT account answers 404, never 403 -- a 403 would confirm the id exists somewhere.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something failed on our side. The requestId in the body is what to quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/account": { "get": { "operationId": "getAccount", "summary": "Read this account", "description": "Which account this key acts for. The first call a wizard or an agent should make: it turns an opaque credential into a name a human can confirm before anything is created under it.\n\nCarries no billing state and no member list -- those are a different scope and, in the case of the member list, not something a machine credential should enumerate.", "tags": [ "Account" ], "security": [ { "apiKey": [ "account:read" ] } ], "parameters": [], "responses": { "200": { "description": "Read this account", "headers": { "X-Request-Id": { "description": "Echoed in the body of any error. Quote it when reporting a problem.", "schema": { "type": "string" } }, "X-TagSentry-Region": { "description": "Which regional database served this response, when it read regional data. A site's region is fixed at creation and is never taken from the request.", "schema": { "type": "string", "enum": [ "EU", "US" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "description": "The account this key acts for. It comes from the key and from nowhere else -- no path, query or body can name a different one." }, "name": { "type": "string" }, "onboarded": { "type": "boolean", "description": "False while nobody has confirmed this account's name. A wizard should say the name is a guess rather than print it as a choice somebody made." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp, UTC." } }, "required": [ "accountId", "name", "onboarded", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired API key. These are deliberately indistinguishable in the response -- distinguishing them would confirm to a caller that a token was once real.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The key authenticated but does not carry the scope(s) this operation requires, or (`domain_not_verified`) the site's domain is not verified, so its consent records are not released.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "No such resource on this account. A site id belonging to a DIFFERENT account answers 404, never 403 -- a 403 would confirm the id exists somewhere.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something failed on our side. The requestId in the body is what to quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/sites/{siteId}/install": { "get": { "operationId": "getSiteInstall", "summary": "Read the install snippet", "description": "Everything needed to install this site: the exact snippet bytes, the public site key, the delivery origin for a CSP entry, and the URLs the client will talk to.\n\nORDER IS THE CONTRACT. The snippet goes in , ABOVE the tag manager snippet, and below nothing except whatever sets the visitor's jurisdiction. It never loads, defers or gates gtm.js -- a total delivery failure of ours leaves the customer with a loaded container, denied Consent Mode defaults and no banner, which is fail-closed and visible.\n\nThis call MINTS what it has to: a site that has never had a public key gets one here, and a site with no ruleset configuration gets the default one published. That is a write on a GET, deliberately -- the customer's whole obligation is to paste one snippet, and an endpoint that asked them to press Generate first would have added an obligation to get the thing that was supposed to be their only one.\n\nSTRICT CONTENT-SECURITY-POLICY. `csp` lists what to allow, read off these exact bytes. The one-line `siteTag` has an inline `onerror` that sets denied Consent Mode defaults if our script cannot load; a policy admits it only with `'unsafe-hashes'` and its hash (`csp.siteTagScriptSrc`, the same on every site). Or use the inline `snippet`, which makes no request before your tags and needs one hash per inline block (`csp.snippetScriptSrc`, this site's own, changed by any banner or blocking change). The tag also works with its onerror removed, and then it FAILS OPEN: if our script cannot load (an outage, a blocked host), nothing sets the denied Consent Mode defaults, Google tags read the unset signals as granted, and they fire with full storage on every page view until the script loads again. Only the Tag Manager consent template, which sets its own denied defaults inside the container, still holds the line. Prefer the hash, or the inline snippet. Either way the banner needs `style-src 'unsafe-inline'` and the origins in script-src, connect-src and img-src.", "tags": [ "Sites" ], "security": [ { "apiKey": [ "install:read" ] } ], "parameters": [ { "name": "siteId", "in": "path", "required": true, "description": "The site id, from GET /v1/sites.", "schema": { "type": "string", "description": "The site id, from GET /v1/sites." } } ], "responses": { "200": { "description": "Read the install snippet", "headers": { "X-Request-Id": { "description": "Echoed in the body of any error. Quote it when reporting a problem.", "schema": { "type": "string" } }, "X-TagSentry-Region": { "description": "Which regional database served this response, when it read regional data. A site's region is fixed at creation and is never taken from the request.", "schema": { "type": "string", "enum": [ "EU", "US" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string" }, "siteKey": { "type": "string", "description": "The site's public key. It appears in every visitor's HTML, so it is public by construction -- put it in a client-side environment variable, not a secret store." }, "region": { "type": "string", "enum": [ "EU", "US" ] }, "snippet": { "type": "string", "description": "The exact bytes to place in . ORDER IS THE WHOLE CONTRACT: this goes ABOVE the tag manager snippet and below nothing except whatever sets the visitor's jurisdiction. It never loads, defers or gates gtm.js." }, "siteTag": { "description": "The one-line install (the default since 2026-09-29): one synchronous script tag naming this site's script, with a fail-closed onerror. Same place as `snippet`, never async or defer.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deliveryOrigin": { "type": "string", "description": "Where the client artifacts are served from, for a Content-Security-Policy entry." }, "rulesetUrl": { "type": "string", "description": "The site's compiled ruleset, which the payload fetches." }, "consentIngestUrl": { "type": "string" }, "monitoringIngestUrl": { "type": "string" }, "parts": { "type": "object", "properties": { "configJs": { "type": "string", "description": "Empty since 2026-09-29: the site's config rides in the bootstrap's call. Emit it first if non-empty." }, "bootstrapJs": { "type": "string", "description": "The inline bootstrap, its call carrying the site's config. Inline, first." }, "tcfStubJs": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "consentModeJs": { "description": "Present only when the site opts into Consent Mode extras. Inline, after the bootstrap.", "type": "string" }, "blocker": { "description": "Present only when the site blocks trackers outside Tag Manager. A SYNCHRONOUS script element with this src, integrity and crossorigin=\"anonymous\", directly after the bootstrap -- never async, deferred or injected -- or hardcoded trackers run before consent. (Until 2026-09-29 this was `blockerJs`, an inline script.)", "type": "object", "properties": { "url": { "type": "string" }, "integrity": { "type": "string" } }, "required": [ "url", "integrity" ], "additionalProperties": false }, "payload": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "tag" }, "url": { "type": "string" }, "integrity": { "type": "string" } }, "required": [ "kind", "url", "integrity" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "loader" }, "js": { "type": "string" } }, "required": [ "kind", "js" ], "additionalProperties": false } ] } }, "required": [ "configJs", "bootstrapJs", "tcfStubJs", "payload" ], "additionalProperties": false, "description": "THE SAME SNIPPET, IN PIECES, for a caller with no HTML file to paste into -- a React root layout, a template helper, a framework plugin. Emit them in the order the order the snippet uses: config, bootstrap, blocker and Consent Mode line if present, TCF stub if present, payload last.\n\nThe two inline pieces must run before anything else on the page and make no network request; the payload is async and must never block. Getting that wrong does not break the page -- it breaks the Consent Mode race the bootstrap exists to win, silently, on somebody else's visitors." }, "ready": { "type": "boolean", "description": "False when something upstream of the paste is missing -- most often that no ruleset has been published yet. `problems` says which, in words meant for a developer." }, "problems": { "type": "array", "items": { "type": "string" } }, "monitoringReady": { "description": "True when `siteTag` runs EVENT MONITORING as soon as it is on the page, whatever `ready` says about the banner: the same one line serves both products, so a monitoring-only site installs exactly this line too (it shows no banner while the banner is offline or another consent tool runs the page, and monitors only where the visitor's consent allows).", "type": "boolean" }, "csp": { "description": "What a strict Content-Security-Policy must allow for this install. Absent when `ready` is false. Merge each list into your own directive; nothing here replaces your policy.", "type": "object", "properties": { "origins": { "type": "array", "items": { "type": "string" }, "description": "Every origin our client loads from or sends to." }, "siteTagScriptSrc": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "script-src for the one-line tag: the origins, `'unsafe-hashes'` and the hash of its onerror handler. The hash is the same on every site. A nonce cannot cover the onerror attribute." }, "snippetScriptSrc": { "type": "array", "items": { "type": "string" }, "description": "script-src for the inline snippet: the origins and one `'sha256-…'` per inline script block. These hashes are this site's (its key is in the bootstrap's call) and change when the snippet does: re-read them after a banner or blocking change." }, "connectSrc": { "type": "array", "items": { "type": "string" }, "description": "The ruleset, consent decisions and tag events." }, "imgSrc": { "type": "array", "items": { "type": "string" }, "description": "The owner's logo on a paid Consent banner." }, "styleSrc": { "type": "array", "items": { "type": "string" }, "description": "The banner puts a