Delivery API overview

The delivery API serves one card per call to your publisher edge. It has one endpoint, GET /v1/fragment: you send your account id and the page URL, doubleshift resolves the fragment and picks the card (how delivery works).

Base URL

https://api.shftd2.com

A call

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.

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. The response never depends on the User-Agent: your edge decides who gets a card (integrate).

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

Response codes

The shared table; each condition in detail is on the endpoint page.

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.

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 429s recur under normal traffic, contact doubleshift. It applies to the delivery API only.

Delivery API

Edge library

Management API

Delivery API overview

Authentication

Caching

Headers

Response codes

Rate limit

​Authentication

​Caching

​Headers

​Response codes

​Rate limit

Authentication

Caching

Headers

Response codes

Rate limit