> ## 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.

# Delivery API overview

> Conventions of the doubleshift delivery API on api.shftd2.com: the X-API-Key header, no-store responses, the response codes, the rate limit and Retry-After, and the X-Request-Id and X-DS-Record-Id headers.

The delivery API serves one card per call to your publisher edge. It has one endpoint,
[`GET /v1/fragment`](https://docs.shftd2.com/api/fragment): you send your account id and the page URL, doubleshift resolves the
fragment and picks the card ([how delivery works](https://docs.shftd2.com/how-it-works.md#resolution)).

```text title="Base URL" theme={"theme":{"light":"css-variables","dark":"css-variables"}}
https://api.shftd2.com
```

```bash title="A call" theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl --request GET \
  --url 'https://api.shftd2.com/v1/fragment?partner_id=<your account id>&page_url=https%3A%2F%2Fyour-domain.example%2Fsome-article' \
  --header 'X-API-Key: <your key>' \
  --header 'X-Agent-UA: GPTBot/1.0'
```

## Authentication

Send your API key in the `X-API-Key` header on every call. Which secret goes where, and why only the
header counts: [Keys and tokens](https://docs.shftd2.com/api-keys.md).

## Caching

Every response, whatever its status, carries `Cache-Control: private, no-store` and no `Vary`. What that
means for a pause or a revoked key: [no cache](https://docs.shftd2.com/how-it-works.md#no-cache).

The response never depends on the `User-Agent`: your edge decides who gets a card ([integrate](https://docs.shftd2.com/integrate.md)).

## Headers

| Header | Direction | Meaning |
| - | - | - |
| `X-API-Key` | request, required | Your API key. |
| `X-Agent-UA` | request, optional | The visiting agent's `User-Agent`, when your edge sends a benign one. Reporting only. |
| `X-DS-Record-Id` | request, optional | Your own id for the page, kept with the delivery when it is a UUID, ignored otherwise. The edge library sends its `record_id`. |
| `X-Request-Id` | response, every status | The delivery number, a UUIDv7 given on receipt. Quote it to support. |
| `X-ABC-Resolution` | response, `200` | How the fragment was found: `rule` or `default`. |
| `Retry-After` | response, `429` | Seconds to wait: `60`. |

In the HTML of a `200`, the delivery number is also on the card's root, `data-ds-delivery`
([card format](https://docs.shftd2.com/api/card-format.md)).

## Response codes

The shared table; each condition in detail is on the [endpoint page](https://docs.shftd2.com/api/fragment.md).

| Code | Meaning |
| - | - |
| `200` | A card. The body follows `format`: the card's HTML (default), its JSON, or both. |
| `204` | No-fill: nothing to serve for this page, or a `page_url` that cannot be used. Empty body. Serve the page unchanged. |
| `400` | A required parameter is missing, or a refused parameter is present. |
| `401` | No API key in `X-API-Key`, or an unknown or revoked key. |
| `403` | The key is valid but belongs to another account than `partner_id`, or a browser sent a cross-origin `POST`. |
| `405` | A method other than `GET`, `HEAD` included. `Allow: GET`. |
| `429` | Too many calls for this API key. Wait for `Retry-After`. |

A `4xx` or `429` body is JSON, `{"ok": false, "error": "…"}`: the `error` text is for people, not for
branching. A `204` has no body. An unexpected error on doubleshift's side is a `204` too: your page never
depends on the call. Causes and fixes: [verify and troubleshoot](https://docs.shftd2.com/verify.md).

## Rate limit

The ceiling is counted per API key, currently 600 calls per minute. Counters are kept per Cloudflare
location, so the limit is approximate, and it may change. A `429` is answered before any delivery is
written, and records none: your edge serves the page without a card. If `429`s recur under normal traffic,
contact doubleshift.

It applies to the delivery API only.


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