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

# Direct delivery logs API

> POST /v1/beacon on logs.shftd2.com: the request, the record format, each response code with what the edge library does, and what a 202 means. For the library's direct delivery logs and for custom senders.

The edge library sends each delivery record here when [`logsToken`](https://docs.shftd2.com/api/edge-library#options) is set. A
custom sender may use the same contract. Which transport fits your site: [delivery logs](https://docs.shftd2.com/delivery-logs.md).

```text title="One record, one request" theme={"theme":{"light":"css-variables","dark":"css-variables"}}
POST https://logs.shftd2.com/v1/beacon
Authorization: Bearer <your logs token>
Content-Type: application/json
User-Agent: doubleshift-edge/1.1.4

{"event":"doubleshift_edge","version":"1.1.4","level":"info","outcome":"served","agent":"ChatGPT-User","page_url":"https://your-domain.example/some-article","duration_ms":412,"record_id":"…","ts":"…","api_ms":63,"status":200,"api_rid":"…","card_written":true,"brand":"…","resolution":"rule"}
```

## Request

**Authorization** `string` *required*

`Bearer` followed by your logs token for direct sending. The token travels in this header only: a request
with a query string is refused (`400`).

**Content-Type** `string` *required*

`application/json`. The body is not compressed: a `Content-Encoding` header is refused (`400`). A request
carrying a `Cookie` header is refused (`403`).

**record** `object` *required*

One delivery record per request, as UTF-8 JSON, at most 8 KiB: one flat object with unique field names and
only string, boolean or safe-integer values. `event` is `doubleshift_edge`; `version` is `1.x.y`, `1.1.1`
or later; `record_id` is a UUID; `ts` is an ISO 8601 timestamp with a timezone, less than 24 hours from
receipt. A body that contains a doubleshift token is refused. A retry sends the same bytes again. The
fields: [delivery records](https://docs.shftd2.com/api/edge-library.md#delivery-records-and-logs).

## Response codes

Only `202` is a success. The library makes at most one second attempt, 2 s after the first, and only after
a `503`, a timeout (10 s) or a network error; every other failure ends in a `beacon_failed`
[diagnostic](https://docs.shftd2.com/api/edge-library.md#diagnostics) with the HTTP status, or the error when no response came.

**202** `accepted`

The record is stored, or was already stored.

**400** `refused`

The request or the record is refused; `error` names why: `query_refused`, `bad_encoding`,
`bad_content_type`, `bad_json`, `bad_version`, `no_record_id`, `ts_out_of_window`, and others.

**401** `refused`

The token is missing, malformed, unknown or revoked.

**403** `refused`

A `Cookie` header (`cookie_refused`), or a logs token issued for Logpush (`wrong_transport`).

**405** `refused`

A method other than `POST`. `Allow: POST`.

**413** `refused`

The body is over 8 KiB.

**429** `refused`

Too many records for this token right now, with `Retry-After`. The library does not retry it.

**503** `retry`

doubleshift cannot store the record right now, with `Retry-After`. The library retries once.

A redirect is not followed and is not retried.

## What a 202 means

`202` confirms that doubleshift has stored the record, including when the same record was already stored.
Counting happens later: it does not confirm that the record was counted, nor that an AI agent read the
card. A timeout or a `503` can come after storage, so neither proves the record was lost.

## Keep the logs token secret

Store it as a Worker secret (`DOUBLESHIFT_LOGS_TOKEN`), never in code or configuration; it allows sending
records only, and doubleshift revokes and replaces it if it is exposed ([keys and tokens](https://docs.shftd2.com/api-keys.md)).


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