Domains
Endpoints under /v1/domains
All endpoints require Authorization: Bearer ck_....
List domains
GET /v1/domains
Scope: domains:list
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number (min 1) |
limit | integer | 100 | One of 1, 5, 10, 25, 50, 100 |
verified | boolean | — | Filter by verification status |
name | string | — | Max 128 chars |
Response 200
{
"count": 0,
"data": []
}Each item in data is a Domain.
Create domain
POST /v1/domains
Scope: domains:create
Register a domain. Subdomain required (e.g. track.example.com).
Rejected if name contains http, www, or /, or is not a valid subdomain hostname.
Request body
{
"name": "track.example.com"
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Subdomain hostname — no scheme, www, or path. Max 128 chars. |
Response 201
{
"id": 1,
"name": "track.example.com",
"verified": false,
"migrated": false
}Verify domain
PATCH /v1/domains/:id/verify
Scope: domains:verify
Checks DNS/CNAME propagation and activates the certificate. No request body.
Rate limit: 1 request per domain ID per 30 seconds (in addition to the global API key limit). Faster polling returns 429 and does not speed up verification.
Path parameters
| Name | Type | Description |
|---|---|---|
id | integer | Domain ID |
Response 200
{
"name": "track.example.com",
"verified": true
}Polling for verification
DNS/CNAME propagation and certificate activation can take several minutes. Poll until verified: true before using the domain in campaigns.
Do not spam verify requests. Each call checks upstream infrastructure (Cloudflare). The API allows one verify per domain ID every 30 seconds — retrying faster returns 429 and does not help.
Wait at least 30 seconds between attempts on the same domain ID. A practical interval is 30–60 seconds.
Delete domain
DELETE /v1/domains/:id
Scope: domains:delete
Response 204
Same quirk as campaign delete — status 204, optional { "message": "..." } body. Treat status as success.