Delivery API

The Delivery API is the read-only, public-facing API that your storefront uses to fetch published content. It is optimized for low latency through Cloudflare KV caching.

Base path

/api/v1/

Endpoints

Get page by path

GET /api/v1/pages/by-path/{path}

Fetch the published content for a URL path. This is the primary endpoint used by the storefront router.

Path parameter:

path — URL path of the page, e.g. about or category/shoes

Query parameters:

Param	Default	Description
`locale`	default locale	IETF locale code, e.g. `en-US`
`preview`	—	Preview token (fetches draft instead of published)

Headers:

Header	Default	Description
`Authorization: Bearer <token>`	required	Delivery (or preview) API key. The key pins the edition via its `target_edition_id` — there is no `?edition` for delivery.
`X-Alokai-CMS-Market`	space default market	Which market’s view to serve (override or inherited).

Example:

curl "https://your-worker.workers.dev/api/v1/pages/by-path/about?locale=en-US" \
  -H "Authorization: Bearer myorg_tok_..." \
  -H "X-Alokai-CMS-Market: germany"

Response:

{
  "id": "pg_01jnk...",
  "path": "/about",
  "content_type": "page",
  "status": "published",
  "layout_id": "pg_01jnk...",
  "data": {
    "componentsAboveFold": [
      {
        "id": "comp_01...",
        "component": "Hero",
        "title": "Welcome",
        "subtitle": "...",
        "uniqueClass": "alokai-cms-abc123",
        "styles": ".alokai-cms-abc123 { ... }"
      }
    ],
    "componentsBelowFold": []
  },
  "locale": "en-US",
  "version": 3
}

Get page by ID

GET /api/v1/pages/{id}

Same as above but fetches by page ID instead of path. Page ids are unique, so the result is market-independent; X-Alokai-CMS-Market only affects which market’s cache segment is used.

Query parameters: Same as by-path.

Market resolution

Within the token’s edition, a request resolves to one page row by the override → inherited rule: if the active market (X-Alokai-CMS-Market) has its own row at the path, that override is served; otherwise the request inherits the edition’s default market row. A request for the default market is always served its own row.

All four delivery variants (preview/published × path/id) run through the same shared resolver as the editor, so the storefront and dashboard can never disagree about which row a market should see. The full rules — including the published-only filter and the orphan-draft tiebreak — are in Page Resolution.

Caching

Published pages are cached in Cloudflare KV on publish. The delivery API reads from KV first:

Cache hit → immediate response, no D1 query
Cache miss → query D1, write to KV, return response

Cache is invalidated when a page is published, re-published, or unpublished.

Cache keys include the market segment, so each market’s resolved view is cached independently:

delivery:path:{spaceId}:{envId}:{marketId}:{path}:{locale}
delivery:id:{spaceId}:{envId}:{marketId}:{pageId}:{locale}

Integrating with the Alokai storefront

In your storefront’s middleware, use the @alokai/cms-api package. The SDK calls /alokai-cms/unified/getPage which internally calls the delivery API.

const page = await sdk.unifiedAlokaiCms.getPage({ path: "/about", locale: "en-US" });

The edition and market the SDK targets are set in its config (edition / market); the SDK forwards them as the token and X-Alokai-CMS-Market header.