# Pixel API

Public contract for creating an account, installing a pixel, and reading contacts. The same pages are for agents and for people.

## How to read this

- `GET /docs.json` is the whole catalog: lessons plus every route below, each with its markdown.
- `GET /docs/{slug}.md` is one lesson or the endpoint reference as markdown. `GET /docs/{slug}` is the same page as HTML.
- `GET /llms.txt` is the short map.
- `GET /openapi.json` is the generated schema. It is thinner than this catalog. The schema UI is `/swagger`.

Production API host: `https://agentpixel.io`. `https://agentpixel.io` and `https://agentpermission.io` are this same process.

## Calls

- JSON errors are `{"detail": "..."}` and an HTTP status.
- A JSON body with the wrong shape is 400 `{"detail": "invalid request"}`. Field names are not listed.
- Send `content-type: application/json` on a JSON POST.
- Signup calls use the header `x-signup-token`. The token lasts one hour from `POST /v1/accounts` and is not refreshed.
- Later calls use `Authorization: Bearer <api_key>`. The key starts with `px_` and is returned once. `prefix` is its first 12 characters.
- On `GET /v1/whoami`, a bad key is 401. On pixel, contact, and setup routes, a bad key is 403.
- Times in responses are UTC.

## Lessons

1. [Signup](/docs/signup.md) : account, email, checkout, API key.
2. [Setup](/docs/setup.md) : pixel, snippet, install check.
3. [Consent](/docs/consent.md) : permission popup and receipts.
4. [Contacts](/docs/contacts.md) : pull people by day or by id.
5. [Evaluation](/docs/evaluation.md) : private scoped access and synthetic examples.

## Left out

Operator routes under `/console`, `/api/admin`, and `/v1/admin` are not in this catalog.

An unlimited key can call [Activate](/docs/endpoints.md#post-v1-accounts-account-id-activate) and [Pipeline](/docs/endpoints.md#post-v1-pixels-pipeline). A paid key receives 403 on those two. This catalog does not say how that key is issued.