# Endpoints

Every route in this catalog. Operator routes are omitted.

# Account

## GET /healthz

Database is answering.

Auth: none.

Success: 200 `{"ok": true}`

Errors:
- 503 `database unavailable`


## GET /v1/plans

Prices a public signup can choose.

Auth: none.

Success: 200 `{"plans":[{"id":"free","selectable":true,"trial_days":30,"setup_fee_cents":0,"resolved_contact_cents":0},{"id":"unlimited","selectable":false}]}`

Notes:
- Public signup starts a 30-day no-card trial, then $1 per account/month. Includes 3 pixels and 500 new contacts per UTC calendar month. No extra charges. Resolution pauses at the limit or after trial until subscribed.
- `unlimited` is not selectable on public signup.


## POST /v1/accounts

Start a 30-day trial without a card. The signup token lasts one hour.

Auth: none.

Body:
- `email` (string, required). Stored lowercased.
- `display_name` (string, required).
- `external_user_id` (string, optional). Unique when you send it.

Success: 201 `account_id`, `status` `pending_email`, `plan` `free`, `signup_token`, `external_user_id`, `email_verified` false. `verification_url` is present only when the confirmation email was not sent.

Errors:
- 400 `invalid email`
- 400 `display name is required`
- 400 `invalid request`
- 409 `email already registered`
- 409 `external user already registered`
- 502 `could not send the confirmation email`

Notes:
- Send the signup token as `x-signup-token`. It expires one hour after this response. There is no refresh call.
- An unlimited key on this same call skips the email and also returns `api_key` and `prefix`. A paid signup does not.


## GET /v1/accounts/{account_id}

Status, plan, email, and whether the email is confirmed.

Auth: signup token.

Success: 200 `account_id`, `status`, `plan`, `email`, `email_verified`

Errors:
- 401 `signup token required`
- 401 `signup token expired`

Notes:
- Poll this until `email_verified` is true and, after checkout, until `status` is `active`.


## GET /v1/email/verify

Confirm the email. The confirmation link lands here.

Auth: none.

Query:
- `token` (string, required).

Success: 200 HTML. The page says "Email confirmed".

Errors:
- 400 `verification token required`
- 404 `verification link not found`
- 400 `verification link expired` (24 hours after the send)

Notes:
- Use `verification_url` from signup when it is present. Otherwise a person opens the email.


## POST /v1/accounts/{account_id}/verification-email

Send the confirmation email again.

Auth: signup token.

Success: 200 `{"sent": true, "status": "sent"}`, plus `verification_url` only when the mailer skipped the send. Already confirmed: `{"sent": false, "status": "already_verified"}`.

Errors:
- 404 `account not found`
- 401 `signup token required`
- 401 `signup token expired`
- 429 `wait before sending the confirmation email again` (one minute)
- 502 `could not send the confirmation email`


## POST /v1/accounts/{account_id}/checkout

Open Stripe Checkout for the $1 per account/month subscription. No usage charges.

Auth: signup token or account Bearer API key.

Success: 200 `url`, `monthly_cents` 100, `setup_fee_cents` 0, `resolved_contact_cents` 0

Errors:
- 404 `account not found`
- 401 `signup token required`
- 401 `signup token expired`
- 502 when Checkout cannot be opened. `detail` says why.

Notes:
- Give `url` to a person. This call does not charge.
- After payment the browser lands on `/v1/checkout/success`. Check `plan` `paid` and a future `paid_until` using `/v1/whoami`. An active trial is not payment confirmation. Do not call the success URL yourself.
- Cancel leaves the subscription unpaid. Open checkout again when ready.


## GET /v1/checkout/success

Browser return after Checkout. Marks the account active when the session is paid.

Auth: none.

Query:
- `session_id` (string, required). Stripe adds this.

Success: 200 HTML. The page says "Setup payment received".

Errors:
- 400 `session_id is required`
- 400 `stripe checkout is not configured`
- 402 HTML when the session is not paid
- 502 HTML when the session cannot be finished

Notes:
- Integrators poll `GET /v1/accounts/{account_id}` instead of calling this.


## GET /v1/checkout/cancelled

Browser return when Checkout is cancelled. No charge.

Auth: none.

Success: 200 HTML. No subscription is activated.


## POST /v1/stripe/webhook

Stripe notifies this process. An integrator does not call it.

Auth: Stripe signature.

Success: 200 `{"received": true}` for a completed checkout and for ignored event types.

Errors:
- 400 `invalid signature`
- 400 `event missing account`
- 502 when Stripe cannot be read

Notes:
- Header `stripe-signature`. The success page can finish the account without this call.


## POST /v1/api-keys

Issue an API key. The secret is in this response only.

Auth: signup token, or an existing API key.

Query:
- `account_id` (required with `x-signup-token`). Omit it when you send a Bearer key.

Success: 201 `{"api_key": "px_...", "prefix": "px_........"}`. `prefix` is the first 12 characters.

Errors:
- 401 `api key or signup token required`
- 401 `signup token required` or `signup token expired`
- 403 `account is not active`
- 403 `confirm your email before creating an API key` (signup token only)
- 401 `api key required`, `invalid api key`, or `api key revoked` on the Bearer path

Notes:
- The signup-token path needs `status` `active` and a confirmed email.
- A Bearer key on an active account can issue another key. This catalog has no customer revoke route.


## GET /v1/whoami

Whose key this is. The secret is not returned.

Auth: API key.

Success: 200 `account_id`, `plan`, `status`, `key_prefix`

Errors:
- 401 `api key required`
- 401 `invalid api key`
- 401 `api key revoked`

Notes:
- A bad key on this route is 401. On setup routes a bad key is 403.


# Pixel setup

## GET /v1/setup

Whether this account has a pixel installed.

Auth: API key, account in good standing.

Success: 200 `good_standing` true, `pixel_count`, `installed_count`, `setup_complete`

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 400 `that install method is not available`

Notes:
- `setup_complete` is true when at least one pixel has `install_status` `installed`.


## POST /v1/pixels

Mint a pixel for a site and return the install snippet.

Auth: API key, account in good standing.

Body:
- `domain` (string, required). A host, such as `example.com`. `https://` and a leading `www.` are removed. A path, query, port, space, or `@` is refused.
- `method` (string, optional). `cms`, `gtm`, and `utm` are refused.

Success: 201 `pixel_id`, `domain`, `install_status` (`not_checked` on a new pixel), `checked_at`, `snippet`, `consent_enabled`, `check_error`.

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 400 `domain is required`
- 400 `domain must be a host, not a page`
- 400 `domain must be a host`
- 400 `that install method is not available` when `method` is `cms`, `gtm`, or `utm` (body or query)
- 409 `domain already registered` when another account owns that host
- 502 `pixel could not be created`

Notes:
- The same account posting the same domain again gets the existing pixel, still as 201.
- When `consent_enabled` is true the snippet is the consent tag (`/px/{pixel_id}.js`). Otherwise it is the immediate pixel snippet.
- Paste the consent tag if you are about to turn consent on. The immediate snippet starts identification without a choice.


## GET /v1/pixels

Pixels on this key's account, oldest first. Snippets are not included.

Auth: API key, account in good standing.

Success: 200 `{"pixels": [{"pixel_id", "domain", "install_status", "checked_at"}]}`

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 400 `that install method is not available`


## GET /v1/pixels/{pixel_id}

One pixel, including the current snippet.

Auth: API key, account in good standing.

Success: 200 same shape as create.

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 404 `pixel not found`
- 400 `that install method is not available`

Notes:
- Another account's pixel is 404. A script alias is not accepted here. Use the canonical `pixel_id`.


## POST /v1/pixels/{pixel_id}/check

Fetch `https://{domain}/` and record whether the HTML contains this pixel id.

Auth: API key, account in good standing.

Success: 200 `pixel_id`, `domain`, `install_status`, `checked_at`, `check_error`

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 404 `pixel not found`
- 400 `that install method is not available`
- 500 `install checker is not configured`

Notes:
- `installed` means the pixel id is in a 200 page. `not_installed` means a 200 page without the id. `unreachable` means the fetch failed.
- A failed fetch leaves a previous `installed` status in place and still sets `check_error`.
- One same-host redirect is followed. The fetch times out in a few seconds.


## PATCH /v1/pixels/{pixel_id}

Change the domain. Refused after the pixel is installed.

Auth: API key, account in good standing.

Body:
- `domain` (string, required). Same host rules as create.
- `method` optional, and `cms` / `gtm` / `utm` are refused.

Success: 200 the pixel, with snippet.

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 400 `domain is required`
- 400 `domain must be a host, not a page`
- 400 `domain must be a host`
- 400 `that install method is not available` when `method` is `cms`, `gtm`, or `utm` (body or query)
- 404 `pixel not found`
- 409 `installed pixel cannot be renamed`
- 409 `domain already registered`


## DELETE /v1/pixels/{pixel_id}

Delete a pixel that is not installed.

Auth: API key, account in good standing.

Success: 204 empty body.

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 404 `pixel not found`
- 409 `installed pixel cannot be deleted`
- 400 `that install method is not available`


## GET /v1/pixels/{pixel_id}/snippets/{action}

Extra paste snippet for one commerce action.

Auth: API key, account in good standing.

Success: 200 `action`, `pixel_id`, `snippet`, `button_snippet` (null when that file is absent).

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 404 `pixel not found`
- 404 `snippet not found`

Notes:
- `action` is `viewed_product`, `add_to_cart`, or `checkout_completed`.


## POST /v1/pixels/{pixel_id}/email-snippet

Email the immediate install snippet.

Auth: API key, account in good standing.

Body:
- `email` (string, required).
- `method` optional. `cms`, `gtm`, and `utm` are refused.

Success: 200 `{"sent": true, "install_status": "..."}`

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 400 `invalid email`
- 404 `pixel not found`
- 429 `wait before sending the snippet again` (10 minutes)

Notes:
- This emails the immediate snippet, including when consent is on. Paste the consent tag from the consent call when the popup should gate identification.


# Contacts and billing

## GET /v1/pixels/{pixel_id}/contacts

Read resolved people. Pass `on` or `after`, one of them.

Auth: API key, account in good standing.

Query:
- `on` (`YYYY-MM-DD`). People whose first resolved UTC day is that date, in id order.
- `after` (integer, zero or greater). People with a greater id. The same `after` returns the same rows.

Success: Day: `pixel_id`, `on`, `contacts`. Cursor: `pixel_id`, `after`, `high_water`, `contacts`. Each contact is `id`, `hem`, `resolved_at` (UTC ISO), `contact` (the stored object).

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 400 `pass on or after`
- 400 `pass on or after, not both`
- 400 `on must be YYYY-MM-DD`
- 400 `after must be zero or greater`
- 404 `pixel not found`

Notes:
- `high_water` is the last id in this page, or the `after` you sent when there are no rows. Pass it as the next `after`.
- An update keeps the original id and the original UTC day. The day filter follows that first day.
- An unlimited key may read any pixel. A paid key may read its own. Another account's pixel is 404.


## POST /v1/pixels/{pixel_id}/contacts

Store people that are already resolved. A customer read uses GET.

Auth: API key, account in good standing.

Body:
- `contacts` (array). Each item is `hem`, `seen_at`, `contact`.
- `hem` is 64 hex characters when `contact` is present.
- `seen_at` is an ISO timestamp. A trailing `Z` is accepted.
- `contact` is an object. `null` or `{}` is a miss and is skipped.

Success: 200 `{"pixel_id", "stored"}`. `stored` counts people written, including updates. Misses are not counted.

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`
- 400 `contact entry must be an object`
- 400 `contact must be an object`
- 400 `hem must be a 64-character hex string`
- 400 `seen_at must be an ISO timestamp`
- 400 `invalid request`
- 404 `pixel not found`

Notes:
- Updating a known `hem` replaces `contact` and keeps the id and the first `resolved_at`.


## GET /v1/billing/quote

What this account would owe. This call does not charge.

Auth: API key, account in good standing.

Success: 200 `plan`, `contact_count`, `setup_cents`, `contact_cents`, `usage_cents`, `total_cents`. Paid is $1 per account/month. Trial and unlimited are zero. No usage charges.

Errors:
- 401 `api key required` when the Authorization header is missing
- 403 `invalid api key`
- 403 `api key revoked`
- 403 `account is not in good standing` when the account is not `active`, or the plan is not `free`, `paid`, or `unlimited`


# Consent

## POST /v1/pixels/{pixel_id}/consent

Turn on the permission popup and publish the policy.

Auth: API key, account active.

Body:
- `controller_name` (string, required).
- `purposes` (array, at least one). Allowed: `analytics`, `resolution`, `newsletter`, `email_sharing`, `phone_sharing`, `partner_email`, `partner_calls`, `partner_sms`. Unknown names are dropped.
- `controller_type` optional. `company` (default), `person`, or `organization`.
- `controller_contact`, `controller_jurisdiction`, `rule_version` optional strings.
- `data_sharing` boolean. False when omitted.
- `contact_channels` optional. Allowed: `email`, `phone`, `sms`, `agentic`.
- `disclosed_parties` optional array of strings.
- `site_policy_url` optional. The site's own privacy policy, a full https:// link. The popup links to it, and the hosted page becomes a short identification notice that adds to it.

Success: 200 `pixel_id`, `consent_enabled` true, `policy_version`, `policy_hash`, `policy_url`, `snippet`, `purposes`. The snippet is `<script async src="{origin}/px/{pixel_id}.js"></script>`.

Errors:
- 400 `invalid request`
- 400 `controller name is required`
- 400 `choose at least one purpose`
- 400 `controller type must be company, person, or organization`
- 401 `invalid api key`
- 403 `account is not active`
- 404 `pixel not found`

Notes:
- Install `snippet`, not the immediate pixel snippet. Identification loads only after the visitor accepts `resolution` on the current policy.
- Saving the same policy text keeps `policy_version`. A text change increments it. Visitors must accept the new hash.
- An unlimited key may configure any pixel. The path id must be the canonical pixel id.


## GET /v1/pixels/{pixel_id}/consent

Consent log for one pixel, newest first, at most 200 rows.

Auth: API key, account active.

Query:
- `state` optional: `accepted`, `declined`, or `withdrawn`.

Success: 200 `pixel_id`, `events`. Each event includes the receipt fields plus `receipt`, `signature`, and `signature_alg` `hmac-sha256`.

Errors:
- 400 `invalid state`
- 401 `invalid api key`
- 403 `account is not active`
- 404 `pixel not found`


## GET /px/{pixel_id}.js

The permission popup. Browsers load this. It is not cached.

Auth: none.

Success: 200 `application/javascript`. `Cache-Control: no-store`.

Errors:
- 404 `consent tag not found` when the pixel is missing, consent is off, or there is no policy hash

Notes:
- The path accepts the canonical pixel id or a script alias. The banner records the canonical id.
- A visitor with Global Privacy Control is treated as a decline and nothing is stored.
- Accepting `resolution` on the current policy is what loads the identification tag.


## GET /v1/policy/{pixel_id}

The current privacy notice as HTML.

Auth: none.

Same handler: `GET /api/v1/policy/{pixel_id}`.

Success: 200 HTML.

Errors:
- 404 `policy not found`

Notes:
- A script alias in the path resolves to the canonical pixel.


## POST /v1/consent/record

The popup writes one choice. A saved choice is 202. An ignored choice is 204 with an empty body.

Auth: none.

Same handler: `POST /api/v1/pixel/fire`.

Body:
- `pixel_id` (string). Canonical id or script alias.
- `visitor_id` (string).
- `url` (string). Page URL. The host must be the pixel domain or a subdomain of it.
- `consent`: `accepted`, `declined`, or `withdrawn`.
- `affirmative` true is required for `accepted`.
- `policy_version_hash` must equal the current policy hash for `accepted`.
- `purposes` for `accepted` must be a non-empty subset of the configured purposes.
- `gpc` true is ignored and stored as nothing.

Success: 202 `recorded` true, `receipt_id`, `policy_version_hash`, `purposes`, `receipt`, `signature`, `signature_alg`. The receipt is `pixel_id`, `receipt_id`, `visitor_id`, `origin`, `consent_state`, `policy_hash`, `purposes`, `recorded_at`.

Errors:
- 403 `{"recorded": false, "reason": "site_mismatch", "domain": "..."}` when the page host is a different site

Notes:
- 204 (empty) covers bad JSON, an unknown shape, Global Privacy Control, a missing id, an unknown pixel, consent turned off, an accept that is not affirmative, a stale policy hash, or a purpose that was not configured.
- Decline and withdraw store an empty purpose list.
- Verify a receipt with `POST /v1/consent/verify`. The signing secret is not in this response.


## GET /v1/consent/check

Whether the latest receipt allows a purpose.

Auth: none.

Query:
- `pixel_id` (required). Canonical id or a script alias.
- `visitor_id` (required).
- `required_purpose` optional, one of the purpose names.

Success: 200 `permitted`, `reason`, and when a row exists: `receipt_id`, `policy_version_hash`, `current_policy_hash`, `purposes`, `recorded_at`, `receipt`, `signature`, `signature_alg`.

Errors:
- 400 `invalid required_purpose`

Notes:
- `reason` is `ok`, `no_consent_record`, `consent_off`, `declined_or_withdrawn`, `policy_version_stale`, or `purpose_not_granted`.
- `permitted` is true only when `reason` is `ok`. No row, and an unknown pixel id, both return `permitted` false and `reason` `no_consent_record` without a receipt.


## GET /v1/consent/receipt

The latest receipt for a visitor, with a signature.

Auth: none.

Same handler: `GET /api/v1/consent/receipt`.

Query:
- `pixel_id` (required).
- `visitor_id` (required).

Success: 200 the check object plus `valid` true, when a receipt exists.

Errors:
- 404 `no consent record`

Notes:
- Accepts a script alias. An unknown id is 404 `no consent record`.


## POST /v1/consent/verify

Check a receipt signature.

Auth: none.

Body:
- `receipt` (object, required). The receipt object from record, check, or the log.
- `signature` (string).

Success: 200 `{"valid": true}` or `{"valid": false}`.

Errors:
- 400 `invalid request`
- 400 `receipt is required`


# Scripts the tag loads

## GET /pixel.js

Identification script referenced by the immediate snippet.

Auth: none.

Success: 200 `application/javascript`.


## GET /pixel.dev.js

Dev beacon. Customer installs use `/pixel.js` or the consent tag.

Auth: none.

Success: 200 `application/javascript`.


## GET /pixel_popup.js

Popup script referenced by the immediate snippet.

Auth: none.

Success: 200 `application/javascript`.


## GET /pixels/{pixel_id}/p.js

Redirect to Delivr's tag for this pixel id.

Auth: none.

Success: 302 `Location` on the Delivr CDN.

Errors:
- 404 `pixel not found` when the id is not 1 to 80 letters, digits, `_`, or `-`

Notes:
- This process does not host that file. A stub pixel id has no tag on the CDN.


## GET /external_api/install-pixel/delivr-pixel

Whether this pixel id belongs on this host. Used by the tag, not by account setup.

Auth: none.

Query:
- `pid` or `dpid` (the pixel id).
- `host` (the page host).

Success: 200 `{"pixel_id": "<id>"}` when the host is that pixel's domain or a subdomain. Otherwise `{"pixel_id": null}`.

Notes:
- Response header `Access-Control-Allow-Origin: *`.


# Unlimited key

## POST /v1/accounts/{account_id}/activate

Mark an account active without changing its plan. A paid customer key receives 403.

Auth: unlimited API key.

Success: 200 `account_id`, `status` `active`, `plan` (unchanged).

Errors:
- 401 `unlimited key required`
- 401 `invalid api key`
- 403 `unlimited key required`
- 404 `account not found`

Notes:
- Public trial becomes active through email confirmation. This call is for a holder of the unlimited key.


## POST /v1/pixels/pipeline

Mint a `cms` or `utm` pixel on a customer's paid account. A paid key receives 403.

Auth: unlimited API key.

Body:
- `domain` (string, required). Same host rules as `POST /v1/pixels`.
- `pipeline` (string, required). `utm` or `cms`.
- `account_id` or `external_user_id`. One of them is required.

Success: 201 `pixel_id`, `account_id`, `domain`, `install_status`, `pipeline`, `snippet`, `pixel_js_url`, `delivr_script_url`.

Errors:
- 400 `pipeline must be utm or cms`
- 400 `account_id or external_user_id is required`
- 400 domain host errors
- 401 `api key required` or `invalid api key`
- 403 `unlimited key required`
- 403 `customer account is not in good standing` (the target must be `active` and `paid`)
- 404 `account not found`
- 409 `domain already registered`
- 502 `pixel could not be created`


# HTML pages

## GET /

HTML front. The Host header picks the pixel site, the permission site, or the API home.

Auth: none.

Success: 200 HTML.


## GET /site/pixel

Pixel marketing page.

Auth: none.

Success: 200 HTML.


## GET /site/permission

Permission marketing page.

Auth: none.

Success: 200 HTML.


## GET /demo

HTML form that provisions a consent tag on the shared demo account.

Auth: none.

Success: 200 HTML.

Notes:
- Customer pixels come from `POST /v1/pixels` after signup. `POST /demo/provision` writes the demo account.


## POST /demo/provision

Form post for the demo page. Creates or reuses a pixel on the demo account and turns consent on.

Auth: none.

Success: 200 HTML containing the tag.

Notes:
- Do not call this to open a customer account.


## GET /log

HTML page. A person pastes a pixel id and an API key to read that pixel's consent log.

Auth: none.

Success: 200 HTML. The page calls `GET /v1/pixels/{pixel_id}/consent`.