# Setup

Mint a pixel for one site, paste the tag, and confirm the homepage contains the pixel id.

You need an API key from [Signup](/docs/signup.md). Send `Authorization: Bearer <api_key>` and `content-type: application/json` on POSTs. These routes require the account to be `active` on the `paid` or `unlimited` plan. A bad key here is 403, not 401.

`method` `cms`, `gtm`, or `utm` on these routes is 400 `that install method is not available`. Leave `method` out.

## 1. Read standing

`GET /v1/setup`

200 returns `good_standing` true, `pixel_count`, `installed_count`, and `setup_complete`. `setup_complete` is true once any pixel is `installed`. 403 `account is not in good standing` means signup is unfinished.

## 2. Create the pixel

`POST /v1/pixels`

```json
{"domain": "example.com"}
```

Send a host. `https://` and a leading `www.` are stripped. A path, query, port, space, or `@` is 400 `domain must be a host, not a page` or `domain must be a host`.

201 returns `pixel_id`, `domain`, `install_status` `not_checked`, `snippet`, `consent_enabled`, and `check_error`. Store `pixel_id`. Posting the same domain again on this account returns that same pixel.

409 `domain already registered` means another account owns the host.

The `snippet` in this response loads identification immediately, unless consent is already on. If the site should ask before identification, do [Consent](/docs/consent.md) next and paste that lesson's snippet instead of this one.

## 3. Paste the tag

Put the snippet on the public homepage. The install check looks at `https://{domain}/` only, and it looks for the pixel id in the HTML.

`POST /v1/pixels/{pixel_id}/email-snippet` with `{"email": "person@example.com"}` emails the immediate snippet. It does not email the consent tag. Wait 10 minutes before sending it again (429).

Extra commerce snippets: `GET /v1/pixels/{pixel_id}/snippets/{action}` where `action` is `viewed_product`, `add_to_cart`, or `checkout_completed`.

## 4. Check the install

`POST /v1/pixels/{pixel_id}/check`

200 returns `install_status` and `check_error`.

- `installed` : the homepage returned 200 and contains the pixel id.
- `not_installed` : the homepage returned 200 and does not contain it.
- `unreachable` : the fetch failed. `check_error` says why.

A failed fetch does not clear a previous `installed` status.

`GET /v1/setup` then reports `setup_complete` true when `installed_count` is at least 1.

## 5. Read it back

`GET /v1/pixels` lists this account's pixels without snippets. `GET /v1/pixels/{pixel_id}` returns one pixel and its current snippet. Another account's id is 404 `pixel not found`. These routes want the canonical pixel id, not a script alias.

`PATCH /v1/pixels/{pixel_id}` with `{"domain": "other.example.com"}` renames a pixel that is not installed. 409 `installed pixel cannot be renamed`. `DELETE /v1/pixels/{pixel_id}` is 204, and 409 `installed pixel cannot be deleted` after it is installed.

Next lesson: [Consent](/docs/consent.md) if the tag should wait for a choice, or [Contacts](/docs/contacts.md) to read people.