Signup

Start a 30-day trial, no card, confirm the email with the 6-digit code, and take an API key. After the trial subscribe for $1 per account/month. Includes 3 pixels and 500 new contacts per UTC calendar month. No extra charges. Resolution pauses at the limit or until subscribed.

Call these paths on the API host you already reached (https://agentpixel.io in production). Send content-type: application/json on every POST that has a body. A refused call returns JSON {"detail": "..."}. A body with the wrong shape returns 400 {"detail": "invalid request"} and does not list the fields.

Store these

• account_id from step 2.
• signup_token from step 2. Send it as the header x-signup-token. It lasts 24 hours. After that, POST /v1/accounts/{account_id}/signup-token with the email and a fresh code issues a new one.
• api_key from step 3, or from step 6 when the person used the link instead of the code. It is shown once and starts with px_. Later calls use Authorization: Bearer <api_key>.

Agents in an MCP client run the same steps as tools: signup_free, then confirm_signup(account_id, code, signup_token), and create_api_key only when the link was used.

1. Read the prices

GET /v1/plans

No auth. Use the selectable free trial. It lasts 30 days without a card. After trial the account costs $1/month. Usage charges and setup fees are zero. Ignore unlimited.

2. Create the account

POST /v1/accounts

{"email": "ada@example.com", "display_name": "Ada"}

external_user_id is optional. When you send it, the same value cannot be registered twice.

201 returns account_id, status pending_email, plan free, signup_token, and email_verified false. When the confirmation email was not sent, the object also has verification_url. When that field is absent, the email was sent.

• 400 invalid email, display name is required, or invalid request
• 409 email already registered or external user already registered
• 502 could not send the confirmation email

3. Confirm the email with the code

The email starts with a 6-digit code. Ask the person to read it to you. Never guess it.

POST /v1/accounts/{account_id}/confirm

{"code": "482913", "signup_token": "<signup_token>"}

200 returns email_verified true and, on the first confirmation with a signup token, api_key and prefix. Store api_key and skip to step 7.

• 400 code is incorrect; N attempts left. A code allows 5 attempts and lasts 24 hours.
• 429 too many wrong codes; call resend_code for a new one.
• New code: POST /v1/signup/resend-code with {"email": "..."}. Limits: 1 per minute, 5 per day. The old code stops working.

Or the person clicks the link

When verification_url is present, GET it. The path is /v1/email/verify?token=.... The response is HTML. 200 means the page contains "Email confirmed". The link expires 24 hours after it was sent.

When verification_url is absent and the person clicks the email link, poll step 4 every 5 seconds, for up to 10 minutes, until email_verified is true. No token needs copying.

Send it again with POST /v1/accounts/{account_id}/verification-email and header x-signup-token. A second send inside one minute is 429 wait before sending the confirmation email again. An address that is already confirmed returns {"sent": false, "status": "already_verified"}.

4. Watch the account

GET /v1/accounts/{account_id} with header x-signup-token.

200 returns status, plan, email, and email_verified. The trial starts as pending_email and becomes active after email confirmation. Resolution pauses when the trial expires unless a paid subscription is active. A missing or expired signup token is 401.

5. Subscribe after the trial (optional during the trial)

POST /v1/accounts/{account_id}/checkout with header x-signup-token.

200 returns url, monthly_cents 100, setup_fee_cents 0, and resolved_contact_cents 0. Give url to a person to authorize the $1 monthly subscription. No usage charges.

You do not call the return URL. After payment, check /v1/whoami using your API key until plan is paid and paid_until is in the future. An active trial is not payment confirmation. If they cancel, no subscription is activated; open checkout again when ready.

Use your account Bearer API key for checkout after the signup token expires. Confirm your email first. An already-paid subscription returns 409.

6. Take the API key

Wait until status is active and email_verified is true.

POST /v1/api-keys?account_id={account_id} with header x-signup-token.

201 returns api_key and prefix. Store api_key. 403 account is not active or confirm your email before creating an API key means step 3 is unfinished.

7. Check the key

GET /v1/whoami with Authorization: Bearer <api_key>.

200 returns account_id, plan free during trial or paid after subscription, status active, and key_prefix. It does not return the secret.

Next lesson: Setup.