Skip to content
traffic.cx
Start free trial

Explore traffic.cx

Already have an account?Log in

Sites API

Add, change and remove sites, goals and chart notes from your own code, for agencies and platforms with many sites.

Updated 14 October 20263 min read

The Sites API sets up tracking from your own code. It suits agencies and platforms that add a site for every new customer, and deploy scripts that leave a note on the chart when a release goes out. It needs a key with the Manage sites permission (sites:write); see API keys.

A key with only this permission can read sites, goals and notes, but not stats. Add Read stats to the same key if it needs both.

Add a site

POST https://api.traffic.cx/v1/sites

bash

curl -X POST https://api.traffic.cx/v1/sites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "shop.example.com", "name": "Example shop", "timezone": "Europe/Berlin", "currency": "EUR" }'
FieldRequiredMeaning
domainyesThe site's domain, without https:// or a path
namenoA label for the dashboard. Default: the domain
timezonenoAn IANA timezone such as Europe/Berlin. Default: UTC
currencynoThree-letter ISO code for revenue. Default: USD

The answer, 201, includes the new site's id (tcx_…). Put it in the tracking snippet from Install & verify. The site is added to the key's team, and counts towards the team's plan like any other.

Read and change a site

  • GET /v1/sites lists the team's sites.
  • GET /v1/sites/{site} answers one site's settings.
  • PATCH /v1/sites/{site} changes any of name, domain, timezone, currency, identity_mode (cookieless or cookie), include_subdomains, allowed_hostnames, allow_datacenter, revenue_lookback_days and features. Send only the fields you change.

bash

curl -X PATCH https://api.traffic.cx/v1/sites/tcx_yoursite \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "include_subdomains": true }'

Remove a site

DELETE /v1/sites/{site} removes the site from the team's dashboards, and visits to it are no longer collected, just as when you delete a site in Settings.

Goals

RequestDoes
GET /v1/sites/{site}/goalsLists the goals
POST /v1/sites/{site}/goalsAdds one
PATCH /v1/sites/{site}/goals/{id}Changes one
DELETE /v1/sites/{site}/goals/{id}Removes one

A goal has a kind and a match:

  • "kind": "event" counts a custom event by name, for example "match": "signup".
  • "kind": "pageview" counts visits to a page, for example "match": "/pricing" or "/blog/**".
  • "kind": "scroll" counts visits that scroll a page past scroll percent (default 50).

name is optional; by default the goal is named after what it matches.

bash

curl -X POST https://api.traffic.cx/v1/sites/tcx_yoursite/goals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "event", "match": "signup", "name": "Signed up" }'

Chart notes

Notes mark a moment on the dashboard's chart: a launch, a campaign or an outage. Each has an at time (ISO 8601) and a text.

bash

curl -X POST https://api.traffic.cx/v1/sites/tcx_yoursite/annotations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "at": "2026-10-16T09:00:00Z", "text": "Released v2.4" }'

GET, PATCH and DELETE work as for goals, at /v1/sites/{site}/annotations and /v1/sites/{site}/annotations/{id}. Notes added with a key show no author.

Verify and troubleshoot

  1. Create a key with only Manage sites and add a test site. Check that it appears in the dashboard's site list.
  2. Add an event goal and a note, then open the site's dashboard and find both.
  3. Remove the test site.

409 means a limit was reached, such as the number of sites a team can have, or a domain that is already tracked. 404 means the site isn't one of the key's team's.

The routes and permission checks are covered by local tests. No request in this guide has been sent to a real customer account as part of publication.