API Overview

Base URLs

Region	Base URL
US	https://api.traceclick.io
EU	https://api-eu.traceclick.io

Use the base URL that matches the region your app was created in.

Tip

The Trace CLI handles base URLs and authentication automatically. Most operations below have a simpler CLI equivalent — see the command reference.

Authentication

All API endpoints require an API key passed in the X-Api-Key header:

curl https://api.traceclick.io/v1/links \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx"

API keys start with tr_live_ for production or tr_test_ for sandbox environments.

When using the CLI, your API key is stored in ~/.trace/config.json and sent automatically. Run trace whoami to verify your credentials.

Caution

Keep your API key secret. Never embed it in client-side code or commit it to version control. The SDK handles its own authentication internally.

Endpoints

App management

Endpoint	Method	CLI equivalent
/v1/apps	POST	trace init
/v1/apps/me	GET	trace apps info
/v1/apps/me	PATCH	trace apps update
/v1/apps/me/rotate-key	POST	trace apps rotate-key
/v1/apps/me/rotate-salt	POST	trace apps rotate-salt
/v1/apps/me/billing/checkout	POST	trace apps upgrade
/v1/apps/me/billing/portal	POST	trace apps billing
/v1/apps/me/dpa	GET	trace apps dpa --status
/v1/apps/me/dpa	POST	trace apps dpa --accept

App management endpoints use /me — your API key identifies which app you are.

Links

Endpoint	Method	CLI equivalent
/v1/links	POST	trace links create
/v1/links	GET	trace links list
/v1/links/{code}	GET	trace links get
/v1/links/{code}	PATCH	trace links update
/v1/links/{code}	DELETE	trace links delete

Privacy

Endpoint	Method	CLI equivalent
/v1/privacy/erase	POST	trace privacy erase
/v1/privacy/erase/{id}	GET	trace privacy erase-status
/v1/privacy/export	POST	trace privacy export

Debug

Endpoint	Method	CLI equivalent
/v1/debug/attribution	POST	trace debug attribution
/v1/debug/reset	POST	trace debug reset

Webhooks

Endpoint	Method	CLI equivalent
/v1/webhooks	POST	trace webhooks create
/v1/webhooks	GET	trace webhooks list
/v1/webhooks/templates	GET	trace webhooks templates
/v1/webhooks/{id}	GET	trace webhooks get
/v1/webhooks/{id}	PATCH	trace webhooks update
/v1/webhooks/{id}	DELETE	trace webhooks delete
/v1/webhooks/{id}/test	POST	trace webhooks test
/v1/webhooks/deliveries	GET	trace webhooks deliveries

Bring Your Own Links

Endpoint	Method	Description
/v1/clicks/record	POST	Record a click from your own landing page

Rate limits

Endpoint	Limit	Scoped by
POST /v1/apps	10 req/min	IP address
GET /v1/apps/me	60 req/min	API key
PATCH /v1/apps/me	30 req/min	API key
POST /v1/apps/me/rotate-key	5 req/min	API key
POST /v1/apps/me/rotate-salt	5 req/min	API key
POST /v1/apps/me/billing/*	10 req/min	API key
*/v1/apps/me/dpa	10 req/min	API key
POST /v1/links	60 req/min	API key
GET /v1/links	120 req/min	API key
PATCH /v1/links/{code}	60 req/min	API key
DELETE /v1/links/{code}	60 req/min	API key
POST /v1/clicks/record	300 req/min	API key
POST /v1/privacy/*	30 req/min	API key
POST /v1/webhooks	30 req/min	API key
GET /v1/webhooks	120 req/min	API key
PATCH /v1/webhooks/{id}	30 req/min	API key
DELETE /v1/webhooks/{id}	30 req/min	API key
POST /v1/webhooks/{id}/test	10 req/min	API key
GET /v1/webhooks/deliveries	120 req/min	API key
POST /v1/debug/attribution	30 req/min	IP address
POST /v1/debug/reset	30 req/min	API key

When you exceed a rate limit, the API returns 429 Too Many Requests. The CLI automatically retries with exponential backoff on rate limit and server error responses.

Errors

The API returns standard HTTP status codes with a JSON error body:

{
  "error": "Short description of the problem"
}

Status	Meaning
400	Bad request — invalid JSON, missing required field, or validation failure
401	Unauthorized — missing or invalid API key, or region mismatch
403	Forbidden — this endpoint requires the Trace CLI
404	Not found — the requested resource doesn’t exist
429	Rate limit exceeded — too many requests, retry later
500	Server error — something went wrong on our end
503	Service temporarily unavailable — try again in a moment

The CLI translates these into friendly messages and retries automatically on transient errors (429, 5xx).

Content type

All request and response bodies use JSON. Set the Content-Type header for POST/PATCH requests:

curl -X POST https://api.traceclick.io/v1/links \
  -H "X-Api-Key: tr_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"deepLinkPath": "/welcome"}'