Get the card for a page
Returns a card for the page named by page_url. The server finds the account’s site for the page host, then the fragment (a routing rule of the site, else its default fragment), then an eligible card. Authentication: the X-API-Key header only. An api_key query parameter is ignored, so a call without the header answers 401 once it reaches authentication (HEAD, parameter and page_url checks come first). A parameter that would override the resolved fragment is refused (400). HEAD answers 405. A POST with a non-empty Origin header whose host or port differs from the request’s answers 403; other methods answer 405.
X-ABC-Resolution values, the rate limit and the maximum page_url length may change.
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'page_url to a fragment, and from a fragment to a card: resolution and card selection.Authorizations
The publisher's API key, kept out of the request URL. Whitespace around the value is trimmed.
Headers
Preferred agent User-Agent reporting channel. A trimmed non-empty value takes precedence over agent_ua and User-Agent. Reporting only: it does not affect card selection.
The caller's own id for the page being served (the edge library sends its page record id, a UUIDv7). Kept with the delivery, lowercased, when it has the shape of a UUID (any version); any other value is ignored, never an error. It does not affect authentication, selection or the response. Caller-supplied: it is not unique.
Fallback reporting value when neither X-Agent-UA nor agent_ua yields a non-empty value. It does not gate serving, affect card selection, or cause a Vary response header.
Query Parameters
Publisher account id. The API key must belong to this account (403 otherwise). An absent or empty value answers 400.
1The page being served. Its host finds the account's site; its path (the query string and the hash are not used) finds the fragment; its page key (normalised host + path) seeds the card choice. A value without a scheme (host/path) is read as https. An absent or empty value answers 400. Once the HEAD and parameter checks pass, a value over 2,048 characters, or one that is not an http(s) URL with a dotted host, answers 204 before authentication, without any database read.
Response representation. The exact value json returns the card payload as JSON; both returns JSON containing the card payload and rendered HTML. Omission, html, and every other value return HTML, so the request value is intentionally not modeled as a closed enum.
Agent User-Agent for reporting only. A trimmed, non-empty X-Agent-UA header takes precedence; otherwise this value is trimmed, and an empty result falls through to User-Agent.
Response
A card is returned when the API key is valid for partner_id, page_url resolves to a fragment of the account (routing rule or site default) that is not paused, selection finds an eligible card, and the selected stored payload parses and passes validation. Body per format: format=json returns CardPayload; format=both returns CardAndHtml; every other format value returns rendered HTML. X-ABC-Resolution says how the fragment was resolved.
The response is of type string.
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'