rest api · v1.0.0

Drive TracerKit over HTTP.

Everything the dashboard does — sites, tags, drafts, health, version history — behind an organization-scoped bearer token. The CLI and SDKs are built on exactly these endpoints.

Authentication
Create a token under Settings → API tokens, then send it as a bearer header. Every request is scoped to that token's organization.
curl https://tracerkit.com/api/v1/sites \
  -H "Authorization: Bearer tkapi_your_token_here"
OpenAPI 3.1 spec →Markdown reference →

Endpoints

GET/api/v1/sites
The sites in the token's organization, including each site's public key and whether the loader has sent its first beacon.
POST/api/v1/sites
Create a site in the token's organization. Returns the site's public key and the install snippet to paste into the site-wide <head>.
{"name": "My store", "domain": "example.com"}
GET/api/v1/sites/{siteId}
One site, with its install snippet.
GET/api/v1/sites/{siteId}/health
Per-tag health: status (firing/degraded/silent/waiting/disabled), last fire time, and 24h fire/error counts. Use after installing the snippet to verify beacons arrive.
GET/api/v1/sites/{siteId}/tags
The managed tags for a site — live and draft, in order.
POST/api/v1/sites/{siteId}/tags
Add a managed tag. Same validation as the dashboard: script/pixel kinds need an https src, inline needs inlineCode. Pass draft: true to create it as a draft (kept out of the live config until published). Live creates record a revision attributed to the token's creator.
{"name": "GA4", "kind": "script", "src": "https://www.googletagmanager.com/gtag/js?id=G-XXXX"}
PATCH/api/v1/sites/{siteId}/tags/{tagId}
Partial update — omitted fields keep their current values and the merged result is re-validated as a whole. enabled toggles the tag. Editing a draft edits it in place (no history until publish); editing a live tag records an "updated" revision.
{"loadStrategy": "lazyOnload", "enabled": true}
DELETE/api/v1/sites/{siteId}/tags/{tagId}
Delete a tag. Live tags record a "deleted" revision and can be restored from history; drafts are discarded without history.
POST/api/v1/sites/{siteId}/tags/{tagId}/publish
Publish a draft ({tagId} is the draft's id). A draft of a live tag overwrites that tag's row (its id stays stable); a standalone draft goes live in place. Records a revision exactly like a dashboard publish.
POST/api/v1/sites/{siteId}/conversions
Post a server-side / offline conversion (Shopify or Stripe webhook, CRM stage change, B2B signup) referencing the visitor's anonymousId. TracerKit enriches it from that visitor's identity profile (click ids + hashed PII the loader collected) and enqueues it to the site's CAPI destinations for high match quality. Pass your own externalUserId to stitch the conversion to a canonical person and enrich from that user's cross-device union (identity resolution). Idempotent on (destination, eventId) so a retried webhook can't double-send. Requires the conversions:write token scope and the Server-side (CAPI) plan.
{"anonymousId": "3f0c...", "eventName": "Purchase", "eventId": "order_1234", "value": 99.5, "currency": "USD"}
GET/api/v1/sites/{siteId}/revisions
Tag change history, newest first. Snapshots are included so a client can inspect what a restore would apply.
POST/api/v1/sites/{siteId}/revisions/{revisionId}/restore
Revert a tag to a recorded snapshot — resurrects deleted tags under their original id. Snapshots are re-validated against the current tag format and obey the same plan gates as edits; the restore records its own revision.