Declare Where Your Pixel Runs

Summary: Every website pixel declares where it runs: a list of your sites, or any site. Visitors are identified only on the sites you list, or on any site if you choose that. Declare it when you create the pixel, in the dashboard or through the API, and change it later in either.

Choose One

List every hostname the pixel loads on. example.com and shop.example.com are different sites, so list both if the pixel runs on both.

Choose Any site only when you cannot list the sites. Anyone who copies the pixel's snippet onto their own site can send data to your pixel.

In the Dashboard

When you create a pixel, the Where will this pixel run? step asks you to choose:

• My websites: paste your sites, one per line or separated by commas.
• Any site I put it on: for agencies and pixels placed on many sites.

You can change the list later in the pixel's settings.

Through the API

Create the pixel with POST /api/v2/pixel/create and send exactly one of the two fields:

curl -X POST https://api.delivr.ai/api/v2/pixel/create \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "title": "My Website Pixel",
    "allowed_origins": ["example.com", "shop.example.com"]
  }'

For any site, replace allowed_origins with "allow_any_origin": true.

The response repeats the declaration as stored:

{
  "response": {
    "pixel_id": "8a755c42-b2b1-...",
    "installation_url": "https://cdn.delivr.ai/pixels/8a755c42-b2b1-.../p.js",
    "allowed_origins": ["example.com", "shop.example.com"],
    "allow_any_origin": false,
    "origins_status": "declared"
  }
}

origins_status is declared when the pixel lists its sites or allows any site, and unverified when it declares neither.

What Delivr Accepts

You can send a domain (example.com) or a full URL (https://Shop.Example.com/pricing). Delivr keeps the lowercase hostname and drops repeats. A pixel can list up to 500 sites.

Delivr refuses these entries with a 400 that names the entry to fix:

• IP addresses, such as 203.0.113.10
• localhost
• A name with no dot, such as intranet
• A bare suffix, such as co.uk
• Wildcards, such as *.example.com

Check the Sites Before Creating

Add "dry_run": true to a v2 request to check the declaration without creating a pixel. Delivr validates and normalizes the sites exactly as it would for a real create. It refuses the same entries with the same 400. It returns the sites as they would be stored:

curl -X POST https://api.delivr.ai/api/v2/pixel/create \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "title": "My Website Pixel",
    "allowed_origins": ["https://Shop.Example.com/pricing", "shop.example.com"],
    "dry_run": true
  }'

{
  "response": {
    "dry_run": true,
    "allowed_origins": ["shop.example.com"],
    "allow_any_origin": false,
    "origins_status": "declared"
  }
}

Nothing is created, so a dry run returns no pixel_id or installation_url. Send the same body without dry_run to create the pixel.

Change the Sites Later

Send the new declaration to PUT /api/v1/pixel/update with the pixel's ID:

curl -X PUT https://api.delivr.ai/api/v1/pixel/update \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "pixel_id": "YOUR_PIXEL_ID",
    "allowed_origins": ["example.com", "shop.example.com"]
  }'

allowed_origins replaces the whole list, so send every site the pixel should keep. [] removes them all. "allow_any_origin" set to true or false turns any site on or off. A field you leave out stays as it is. The sites follow the same rules as create. They are saved before anything else in the request, so a refused site leaves the pixel unchanged.

When the request sends either field, the response's pixel includes allowed_origins, allow_any_origin and origins_status as stored.

Test Keys

A test API key calling POST /api/v2/pixel/create gets a fixed sample response in the same shape, marked with the response header X-Delivr-Mode: test. No pixel is created, with or without dry_run.

v1 Is Deprecated

POST /api/v1/pixel/create keeps working, with both fields optional, until April 24, 2027. A pixel created there without either field has no declared sites. Every v1 response carries these headers:

Deprecation: @1792800000
Sunset: Sat, 24 Apr 2027 00:00:00 GMT
Link: </api/v2/pixel/create>; rel="successor-version"

To move to v2, change the path and add allowed_origins or allow_any_origin to the body. Nothing else changes.

Next Steps

• Pixel and DSP Events API: install the pixel and query its events
• Understanding Resolution Rates: what to expect after you install
• Create pixel (v2) reference: the full request and response schema