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 : account, email, checkout, API key. 2. Setup : pixel, snippet, install check. 3. Consent : permission popup and receipts. 4. Contacts : pull people by day or by id. 5. Evaluation : 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 and Pipeline. A paid key receives 403 on those two. This catalog does not say how that key is issued.