Signup

Start a 30-day no-card trial, confirm the email, 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 expires one hour after the account is created. There is no call that refreshes it.
• api_key from step 6. It is shown once and starts with px_. Later calls use Authorization: Bearer <api_key>.

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

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, a person opens the email. Poll step 4 until email_verified is true.

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.