---
title: "Save a retargeting pixel"
method: POST
path: "/api/pixels"
tags: ["Retargeting Pixels"]
---

# Save a retargeting pixel

`POST /api/pixels`

## Request

- Base URL: `https://www.flyn.to`
- URL: `https://www.flyn.to/api/pixels`
- Auth: HTTP bearer

Saves a pixel owned by the caller and tagged with the current workspace. Attach it to links with `pixelIds`.

**Auth:** API key (`Bearer flyn_sk_live_...`), or the signed-in dashboard session cookie when no API key header is sent. MCP OAuth access tokens are not accepted here and get 401.

**Plan:** Pro, Lifetime or Team (a member of a paying owner's workspace has the effective plan `team`) only; Free gets 403 `UPGRADE_REQUIRED`. At most 50 pixels per user.

**Rate limit:** 20 requests per 60 s per client IP, fixed window, in memory per server instance, checked before authentication. The bucket is shared with PATCH.

## Request body

- PixelCreateRequest
  - `provider` 'meta' | 'google_ads' | 'ga4' | 'gtm' | 'linkedin' | 'twitter' | 'tiktok' | 'pinterest' | 'quora' | 'reddit' | 'snapchat' | 'microsoft' | 'adroll', required
  - `value` string, required: Pixel or tag id (trimmed). The same pattern applies to every provider.
  - `label` string: Trimmed and cut to 80 characters. Empty or missing: the provider's display name, for example "Meta (Facebook) Pixel".

## Response `201`

Saved.

- PixelEnvelope
  - `pixel` Pixel, required
    - `id` string, uuid, required
    - `provider` 'meta' | 'google_ads' | 'ga4' | 'gtm' | 'linkedin' | 'twitter' | 'tiktok' | 'pinterest' | 'quora' | 'reddit' | 'snapchat' | 'microsoft' | 'adroll', required
    - `value` string, required: Pixel or tag id.
    - `label` string, required
    - `created_at` string, date-time, required
    - `is_owner` boolean: List responses only: true when the caller created the pixel. Only the creator can edit or delete it.

## Other responses

- `400`: Messages: "Invalid JSON", "Unknown pixel provider", "That pixel ID contains invalid characters. Use only letters, numbers, dots, dashes, underscores (and a comma for AdRoll).", "You've reached the 50 pixels limit.".
- `401`: No valid API key and no dashboard session. Messages: "Invalid or revoked API key", "API key has expired", "Unauthorized. Sign in to the dashboard, or pass a Bearer API key in the Authorization header.", or "Unauthorized" when the session lookup itself fails. An MCP OAuth token lands here too.
- `403`: Free plan (code `UPGRADE_REQUIRED`) or a suspended account.
- `429`: More than 20 writes in the window. Counted per client IP. Retry-After gives the seconds until the window resets.
- `500`: Insert error.

---

[API](https://skmtc.dev/flyn/apis/flyn-api.md) · [All operations](https://skmtc.dev/flyn/apis/flyn-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flyn/apis/flyn-api/revisions/977962a98ccb?raw)