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

> ## Agent Instructions
> Publishers integrate one API: GET https://api.shftd2.com/v1/fragment?partner_id=<account id>&page_url=<page URL>, called from their edge for AI-agent requests only, with the API key in the X-API-Key header, never in the query string.
> A 200 carries the card. A 204 means no card: serve the page unchanged.
> The management API (https://api.shftd2.com/v1/me, /v1/sites, /v1/cards, /v1/keys) is optional tooling for scripting setup. It takes its own management token (Authorization: Bearer ds_mgmt_…). Its limits (120 requests and 60 writes per minute per token) do not apply to the delivery API.
> Delivery logs reach doubleshift only through direct delivery logs (POST https://logs.shftd2.com/v1/beacon with a logs token; the edge library with a logsToken is its provided client, and a custom sender may use the same endpoint) or a Cloudflare Logpush job configured with doubleshift. Otherwise doubleshift sees only its own API activity.

# Choose your edge

> Pick the integration path for your stack (Cloudflare Worker, Amazon CloudFront, Vercel / Next.js, or ESI) and the rules every edge keeps: the agent gate, X-Agent-UA, where the card lands, the page cache contract and the timeout budget.

The integration lives at your edge, never in a browser. Every path starts with steps 1 to 3 of the
[Quickstart](https://docs.shftd2.com/quickstart.md): a site, a fragment its pages resolve to, and a delivery key.

| Your stack | Path | Status |
| - | - | - |
| Cloudflare | [Cloudflare Worker](https://docs.shftd2.com/integrate/cloudflare-worker.md) | **Recommended.** Reference implementation: the doubleshift edge library, one file, no dependency. |
| Amazon CloudFront | [CloudFront kit](https://docs.shftd2.com/integrate/cloudfront.md) | **Release candidate.** A CloudFront Function and a Lambda that runs the doubleshift edge library. |
| Vercel / Next.js | [Two destinations](https://docs.shftd2.com/integrate/vercel-nextjs.md) | Reference implementation. |
| Akamai, Fastly, Varnish | [ESI tag](https://docs.shftd2.com/integrate/esi.md) | Reference examples per CDN — adapt to your configuration and run [Verify](https://docs.shftd2.com/verify.md). |

![The ESI tag or Worker sits between visitor and origin; an agent User-Agent gate decides whether to call doubleshift](https://mintcdn.com/doubleshift/sw4Ab4HuCk7yFPgK/images/diagrams/edge-integration-lt.svg?fit=max\&auto=format\&n=sw4Ab4HuCk7yFPgK\&q=85\&s=9f6c9be82223109cda76f1699ffd142e)

Only an AI-agent User-Agent opens the gate to GET /v1/fragment; humans pass straight through.

## The paths

### Cloudflare Worker

The doubleshift edge library runs in a Worker on your site's route and applies the rules below for
you. The [Quickstart](https://docs.shftd2.com/quickstart.md) installs it, [Cloudflare Worker](https://docs.shftd2.com/integrate/cloudflare-worker.md)
covers what comes after, and its options are in the [edge library reference](https://docs.shftd2.com/api/edge-library.md).

### Amazon CloudFront

A CloudFront Function sends agent requests to a Lambda that reads your page through the distribution and runs the
same edge library. The kit and its installation are in [Amazon CloudFront](https://docs.shftd2.com/integrate/cloudfront.md). If CloudFront sits
in front of a Varnish, use this path rather than ESI in that Varnish ([ESI](https://docs.shftd2.com/integrate/esi.md)).

### Vercel / Next.js (two destinations)

A proxy keeps humans on the normal page and rewrites agents to a route handler that adds the card.
The two files are in [Vercel / Next.js](https://docs.shftd2.com/integrate/vercel-nextjs.md).

### ESI: Akamai · Fastly · Varnish

One tag in your template, resolved by your CDN's Edge Side Includes for AI agents only. The tag and
the CDN rules are in [ESI](https://docs.shftd2.com/integrate/esi.md).

## How your page is composed

Your integration fetches the page from your origin or cache and adds the card and the in-content
brand line. It never sends the article HTML to doubleshift: the call carries your account id, the
page URL and, optionally, the agent's `User-Agent`. Do not forward visitor cookies or authorization
headers. The API key stays server-side, in the `X-API-Key` header; see [API keys](https://docs.shftd2.com/api-keys.md).

**Your page must never depend on doubleshift.** On a no-fill, an error or a call over your
[timeout budget](#timeout-budget), serve the page without a card. Before going live, simulate a
failure and a timeout on a test page.

## The agent gate

* **Only AI-agent requests call doubleshift.** Match the visitor's `User-Agent` against the agent
  markers, whole words only; the canonical list is in [AI agents](https://docs.shftd2.com/api/agents.md).
* **Decide on every request**, cache hit or miss, in front of the cache. A decision taken when the
  page enters the cache depends on who filled it.
* **Documents only.** Compose a `GET` answered `200 text/html`. Leave `HEAD`, your framework's data
  and prefetch requests, and every other status untouched, redirects included.

### Report the agent in X-Agent-UA

Send the visiting agent's `User-Agent` in `X-Agent-UA` and keep a benign `User-Agent` on the call:
the endpoint's edge protection blocks bot User-Agents. The value only feeds per-agent reporting.
Where a CDN cannot set that header, send the `agent_ua` query parameter, URL-encoded; it then shows
in every log that records URLs.

## Where the card must land

Why this spot matters is in [How delivery works](https://docs.shftd2.com/how-it-works.md#where-the-card-lands). At your edge:

* Place the card, intact, **immediately before the article element**, or first in `<main>`. Not
  inside the article, not at the end of `<body>`.
* Add the brand disclosure as the article's **first paragraph**, only when a card is served:
  `<p><strong>Featured advertiser on this page:</strong> <brand>.</p>`.
* When that spot is missing, serve the page as it is. With the Cloudflare library, set `container`
  if your article element is not `<article>`; a page without it is served intact and no card is
  requested: the card is never appended at the end of the document.

## The page response: cache contract

doubleshift never caches its answers ([No cache](https://docs.shftd2.com/how-it-works.md#no-cache)). The response of **your
page** to the agent is yours. The Cloudflare Worker library applies the header rules below to every
page it enriches. A page it serves without a card goes out as your origin or cache answered it,
headers included, like the human page. On the other paths, apply these rules in your configuration,
at least to every response that carries a card:

* **Never let the human page vary by visitor.** The cached human page must not read the
  `User-Agent` nor call doubleshift.
* **Serve the agent response with** `Cache-Control: private, no-store` or
  `public, max-age=0, must-revalidate`, **and no validators** (`ETag`, `Last-Modified`). Build these
  headers from scratch; never copy the origin's `s-maxage` or CDN-specific headers.
* **Never forward a conditional request on the agent path.** Drop `If-None-Match` and
  `If-Modified-Since`: a `304` leaves nothing to compose.
* After injecting, **drop `Content-Length` and `Content-Encoding`** if your path buffers the body.
* **Check both orders**, cold and warm: see [Verify and troubleshoot](https://docs.shftd2.com/verify.md).

## Timeout budget

Budget **800 ms** for the call from a CDN edge: `timeoutMs` with the Worker library, the include
timeout on an ESI stack, where `onerror="continue"` renders the page without the card. On serverless
platforms (Vercel, Netlify functions…), use **about 2,500 ms**: a cold start alone can exceed
800 ms. Record a timed-out call apart from a no-fill.

## Moved

These sections now have their own pages.

### Options

The edge library's options and defaults are in the [edge library reference](https://docs.shftd2.com/api/edge-library.md#options).

### Diagnostics

The edge library's diagnostics are in the [edge library reference](https://docs.shftd2.com/api/edge-library.md#diagnostics).

### Verify

The checks and the troubleshooting are in [Verify and troubleshoot](https://docs.shftd2.com/verify.md).

### Direct delivery logs

What each way of sending delivery records gives you is in [Delivery logs](https://docs.shftd2.com/delivery-logs.md).


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