Select a site on a request

Every request to the client API and to decide says which of your sites it is for, with the site’s id in the x-edgekit-site-id header. The SDKs set the header for you from their siteId option: see the @edgekitcloud/client-browser and @edgekitcloud/client-server references. Set it yourself only when you call the API directly.

To find a site’s id, see The site id.

Send the header

curl -i https://your-tenant-host/v1/id/config \
  -H 'x-edgekit-site-id: site_daily_example'

const response = await fetch('https://your-tenant-host/v1/id/config', {
  headers: { 'x-edgekit-site-id': 'site_daily_example' },
});

if (!response.ok) {
  const { error } = await response.json();

  throw new Error(`${response.status} ${error.code}: ${error.message}`);
}

The header selects a site; it is not a credential. It can only select one of your own organization’s sites. Routes that need a credential check it as well: an API key, an allowed browser origin or an EdgeKit session, depending on the route.

How the site is resolved

The id is looked up in your newest deployment, not in the draft. A site resolves when it is in that deployment and its status is active. Unknown, disabled and not-yet-deployed sites all get the same answer, so the response never tells a caller which ids exist.

Status	Code	Message	Cause
`400`	`bad_request`	`Missing site id.`	No `x-edgekit-site-id` header.
`404`	`not_found`	`Unknown site.`	The id is unknown, the site is disabled, or it is not deployed yet.
`403`	`forbidden`	`This origin is not allowed for the selected site.`	A browser request from an origin the site does not allow.
`403`	`forbidden`	`This key is not pinned to the selected site.`	An API key issued for a different site.

Every response from a route that reads the header carries Vary: x-edgekit-site-id, errors included, so a shared cache never serves one site’s answer for another. If you put a cache in front of EdgeKit, keep the header in its cache key.

A browser navigation cannot set a header. The one decide route a navigation reaches, GET /v1/decide/forward, takes the site as the site query parameter instead, and the header wins when both are sent. See the decide API reference.

Send the same id with events

The tracker sends the site id as its app id (aid): see the @edgekitcloud/analytics-browser reference. Each event is filed with a site_id:

the aid the tracker sent, exactly as sent, or
_unresolved when the tracker sent none.

The collector never refuses an event because of its site, and it does not check that the id exists. An event with a mistyped id is stored under that mistyped id. A site’s own analytics settings apply only to events whose id matches one of your deployed sites, whatever its status. An event with any other id is collected under your organization’s settings and the default cookie settings.