> ## Documentation Index
> Fetch the complete documentation index at: https://www.getsoundlink.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing pixels

> Save, list, delete, and test organization Meta pixels — including default and send-health fields.

Store Meta Conversions API credentials for your organization: save or rotate a token, set a default, list pixels (never the token), delete, and send a live test event.

Requires custom pixels to be enabled for your organization. Otherwise every route returns `403 custom_pixel_not_enabled`. Scopes: `pixels:read` to list, `pixels:write` to save, delete, or test — see [Authentication](https://www.getsoundlink.com/docs/authentication.md#scopes-v1).

> [!NOTE]
>
> These routes manage organization pixel credentials. They are separate from the Meta
> pixel fields on [self-serve soundlink create](https://www.getsoundlink.com/docs/creating-soundlinks.md#meta-pixel).
> `isDefault` only affects the app soundlink picker — create via the API never applies a default.

## Save or rotate a pixel

`PUT /v1/pixels/{pixelId}`

At least one of `accessToken` or `isDefault` is required. `platform` must be `meta`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X PUT 'https://api.getsoundlink.com/v1/pixels/PIXEL_ID' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "platform": "meta",
    "accessToken": "EAAB...",
    "isDefault": true
  }'
```

Expected (`200`). The response never includes the access token:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "id": "PIXEL_ID",
    "platform": "meta",
    "isDefault": true,
    "status": "ok",
    "lastErrorCode": null,
    "errorSince": null
  },
  "meta": { "requestId": "..." }
}
```

| Situation | Result |
| - | - |
| New `pixelId` for your organization | Pixel is saved (`accessToken` required) |
| Same `pixelId` you already own | Token replaced when `accessToken` is sent; `isDefault` updated when sent |
| Another `pixelId` for the same organization | Saved alongside existing pixels |
| Pixel owned by another organization | `409 meta_pixel_conflict` |
| Access token already used with another pixel | `400 invalid_request` |
| `platform` other than `meta` | `400 invalid_request` |

`Idempotency-Key` is not required. Repeating the same request is safe.

## List pixels

`GET /v1/pixels`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS 'https://api.getsoundlink.com/v1/pixels' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET'
```

Expected (`200`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "pixels": [
      {
        "id": "PIXEL_ID",
        "platform": "meta",
        "isDefault": true,
        "status": "ok",
        "lastErrorCode": null,
        "errorSince": null
      }
    ]
  },
  "meta": { "requestId": "..." }
}
```

`status`, `lastErrorCode`, and `errorSince` reflect recent Conversions API send health.

## Delete a pixel

`DELETE /v1/pixels/{pixelId}`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X DELETE 'https://api.getsoundlink.com/v1/pixels/PIXEL_ID' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET'
```

Expected (`204`) with an empty body.

| Situation | Result |
| - | - |
| Pixel not configured for your organization | `404 not_found` |
| Any soundlink still uses the pixel | `409 pixel_in_use` (`details.smartLinkCount`) |

## Send a test event

`POST /v1/pixels/{pixelId}/test-events`

Sends a live Meta Conversions API event named `Soundlink Stream` to the stored pixel and token. This is not a sandbox event — it appears in Events Manager.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST 'https://api.getsoundlink.com/v1/pixels/PIXEL_ID/test-events' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET'
```

Expected (`200`):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": { "status": "sent", "pixelId": "PIXEL_ID" },
  "meta": { "requestId": "..." }
}
```

Unknown `pixelId` for your organization returns `404`. A rejected pixel id or token returns `400 invalid_request`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.