# 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`

```json
{"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](/docs/setup.md).