# HTTP API

Every public read of the catalog, how long each is cached and what purges it.

## Read from a storefront

A storefront Worker in the same Cloudflare account can bind to Catalog's
`Storefront` entrypoint. Bind to the Catalog Worker for that environment:

```jsonc
{
  "services": [{ "binding": "CATALOG", "service": "orbcatalog", "entrypoint": "Storefront" }],
}
```

Use the Catalog client's `fetch` option to send each request to
`env.CATALOG.fetch(request)` instead of the network. The binding serves the
public delivery reads and uses Workers Cache, without the per-address miss
budget. Catalog sends publish purges to both the public and Storefront caches.
The binding cannot reach staff, Source or change-feed routes.

Browsers, storefronts outside Workers and Workers in another Cloudflare
account use the public Catalog URL. Cache misses on that URL still count
towards the route's per-address budget.

## Routes and cache lifetimes

The table shows standard lifetimes. An answer showing any `limited` offer is fresh for 10 seconds, with a 5-second revalidation window and up to one day of stale-if-error. Supplying `channel` to a listing or product `find` includes prices and uses the shorter [offer lifetime](#product-cards-with-prices).

| Route                                                                                                                               | What                                                                                                                                                                                                                                                                                   | Cache (browser / edge)                                                                     | Tags                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `GET /v1/products/{ref}?locale=&fallback=default`                                                                                   | Published base data, one locale, no Channel; `urls` by Channel                                                                                                                                                                                                                         | `max-age=60` / edge `max-age=600`, both `stale-while-revalidate=600, stale-if-error=86400` | `p:{h(ref)}`, `e:` of each entry it links, `catalog`                                       |
| `GET /v1/products?category=&locale=&limit=&after=`                                                                                  | Cards of a category, pinned first, then newest                                                                                                                                                                                                                                         | 60 / 600                                                                                   | `c:{h(category)}`, `e:` of each entry a card links, `catalog`                              |
| `GET /v1/categories/{ref+}?locale=&fallback=default`, `GET /v1/categories?parent=&locale=`                                          | A category with its `path` to the root and whether it `hasChildren` in the locale, the tree in position order; a ref may hold slashes (`outdoor/rucksaecke`)                                                                                                                           | 60 / 600                                                                                   | `c:{h(ref)}` of every category shown, ancestors included; `roots` for the roots; `catalog` |
| `GET /v1/registers/{register}/entries/{ref}?locale=&fallback=default`, `GET /v1/registers/{register}/entries?locale=&limit=&after=` | An entry of a register, such as a brand, and a register's entries by name                                                                                                                                                                                                              | 60 / 600                                                                                   | `e:{h(register/ref)}` of every entry shown; `r:{h(register)}` for the list; `catalog`      |
| `GET /v1/find?q=&kind=&register=&locale=&limit=`                                                                                    | Type-ahead: up to 50 products (cards), categories or entries whose name in the locale holds every word typed, names that start with it first; a product by the start of each word                                                                                                      | 60 / 600                                                                                   | `p:`, `c:` or `e:` of everything shown; `r:{h(register)}` with a register; `catalog`       |
| `GET /v1/routes/{slug}?locale=`                                                                                                     | Which product, category or entry a slug names, and its slug now; `moved` for a slug it held before                                                                                                                                                                                     | 60 / 600, a moved one 30 like a miss                                                       | `p:`, `c:` or `e:` of the target                                                           |
| `GET /v1/products/{ref}/offers?channel=`                                                                                            | Every variant's offer of one product                                                                                                                                                                                                                                                   | `min(30, next price step)` / `min(120, next price step)`, `stale-while-revalidate=30`      | `op:{h(ref)}`, `offers`                                                                    |
| `GET /v1/offers/{sku}?channel=`                                                                                                     | One SKU's offer                                                                                                                                                                                                                                                                        | same                                                                                       | `o:{h(sku)}`, `op:{h(ref)}`, `offers`                                                      |
| `GET /v1/shops`                                                                                                                     | The shop's identity as the settings in force say: its name, its languages and each Channel's currency, gross or net `prices`, country, languages and storefronts, and the capabilities resources bring by label, which OrbCart, OrbPage and the shop read rather than keep (`shops()`) | 60 / 600                                                                                   | `settings`, purged by every settings publish                                               |
| `GET /v1/openapi.json`                                                                                                              | The contract with every published Type as a schema, and each route's problems by status and code                                                                                                                                                                                       | 60 / 600                                                                                   | `schema`                                                                                   |
| `GET /v1/media/{id}?locale=`                                                                                                        | A file of the media library as a shop shows it: its `url` with every narrower rendition as `srcset`, its `focalPoint` and its `alt` in the locale (`media(id, { locale })`)                                                                                                            | 60 / 600                                                                                   | `m:{h(id)}`, `catalog`                                                                     |
| `GET /v1/locations?channel=`                                                                                                        | The open Locations that serve a Channel, by name: address, coordinates, phone, services, the weekly hours and the next 14 `days`, each with when it is open as moments and why it differs (`locations.list(channel)`)                                                                  | 60 / 600, ending when the first of them starts its next day                                | `locations`, `catalog`                                                                     |
| `GET /v1/appointments/free-times?location=&sku=&from=&days=&quantity=&resource=`                                                    | When a product may start at a Location for up to 14 days, each start with its end and resources (`appointments.freeTimes(…)`)                                                                                                                                                          | 10 seconds at most                                                                         | `offers`                                                                                   |
| `GET /media/{id}/{version}`                                                                                                         | An owned original at its full SHA-256 digest; `current` reads a mutable registered private original                                                                                                                                                                                    | 31536000 / 31536000, immutable; `current`: 30 / 30                                         | Owned images need no purge; `current`: `m:{h(id)}`                                         |
| `GET /media/{id}/{version}/{width}`                                                                                                 | The versioned image scaled down to a rendition width as WebP; wrong versions or widths are `404 media_not_found`, never replacement bytes                                                                                                                                              | same                                                                                       | same                                                                                       |
| `GET /.well-known/jwks.json`                                                                                                        | The catalog's public keys, which verify every event it signs ([webhooks](/docs/integrate/catalog-changes))                                                                                                                                                                                  | 60 / 600                                                                                   | `catalog`                                                                                  |

- Every query is a strict allowlist: an unknown parameter or a repeated scalar parameter is `400 parameter_unsupported`, so every key in the cache is a key we meant. Explicitly declared bounded arrays use repeated parameter names within their declared limits. A malformed value is `400 parameter_invalid` at its pointer, such as `#/query/locale`.
- Every public read has one spelling: its parameters in the route table's order, a default left out, a number without leading zeros, each value percent-encoded but for RFC 3986's unreserved characters (`A-Z a-z 0-9 - . _ ~`). Any other spelling (`?locale=de&category=angebote`, `limit=25`, `limit=010`, `outdoor/rucksaecke` for `outdoor%2Frucksaecke`) is a `308` to it, decided from the URL alone before the miss budget and kept as long as base data, so a scan that varies only the spelling never reaches the database. There is no generic, unbounded `ids=` read. Native batch operations such as category presence explicitly bound their input arrays and query work.
- An explicitly supplied default redirects too: `days=7` on appointment free times receives a `308` to the URL without `days`. Omit defaults or follow redirects, for example with `curl -L`.
- `HEAD` answers as `GET` does, with its status and headers and no body, so a CDN, a link checker or `curl -I` sees what is there. A `HEAD` of an image reads none of its bytes.
- **Renditions.** An image is shown at 160, 320, 640, 960, 1280 or 1920 px and at no other width: every width the catalog hands out is snapped up to the next of these, and a width at or past the original is the original. Where `MEDIA_TRANSFORM` is `cloudflare`, the first request of a rendition makes it through Cloudflare's Images binding and keeps it in the bucket, so each picture at each width is paid once per byte version; `bunny` puts a bunny.net pull zone in front of `/media/{id}/{version}` and asks it for `?width=`, at a flat price per website; `imgproxy` is an externally operated choice; `none` shows only the originals. Every delivered image carries its narrower renditions as `srcset`, so a page gives `sizes` and a phone loads the width its space needs. OrbCart's line image is the widest rendition at most 400 px on its longer side.
- **Registered private images.** `/media/{id}/current` and its Cloudflare variant route serve selected registered originals after their transactional media task installs a protected locator. Image delivery reads private storage, not Postgres, and never exposes the locator or raw object key. HEAD and conditional GET use the same validators; generated variant keys encode the whole opaque original ETag. Store identity must match before raw access. Public CDN references keep their exact external URLs and are never proxied or redirected. See [private storage and protected-origin recipes](/docs/catalog/media-storage#deliver-registered-images); CloudFront needs an explicit cache policy and does not consume Catalog's targeted CDN headers or tag purges automatically.
- Never `s-maxage` (Cloudflare turns stale-while-revalidate off with it). The edge lifetime goes in the header the CDN reads, which its adapter names: `Cloudflare-CDN-Cache-Control` on Cloudflare (the family's rule, measured in S1), `CDN-Cache-Control` (RFC 9213) on Varnish and other CDNs.
- Product pages keep base data separate from offers. Cards may include an offer by asking with `channel`, using the shorter offer lifetime for the whole answer. Every lifetime is clamped to the next moment the answer changes on its own: a scheduled version, a product joining or leaving a listing, a price step. A boundary inside the fresh lifetime ends it there, drops `stale-while-revalidate` and sends `stale-if-error=0`; a boundary beyond it but inside the stale windows trims them to end at the boundary. Any answer cut this way is `200`, never `304`, so a sale that starts at 12:00 is live at 12:00 without a purge, and nothing serves the old price past it, not even when the origin fails.
- A product scheduled for Friday 09:00 is served, listed in its categories and found at its new slug from 09:00, with every answer before it living until 09:00. The read judges the time; nothing has to run at 09:00 for the storefront to be right.
- Weak `ETag` over the body; `304` only at the default lifetime. A product that is not there is `404 product_not_found`, `public, max-age=30, stale-if-error=0`, tagged with its `p:` tag, so its first publish clears it. No `410`.
- Misses are rationed. A request the cache did not answer spends from a budget per route and client network before it reads the database; over budget is `429 rate_limited`, `private, no-store`. A scan of made-up refs, each a miss past the 30-second negative cache, cannot become a scan of Postgres.
- Storefront reads through `catalog({ url })` retry once after one second if the connection fails, the answer is `429` or `5xx`, or it carries `Retry-After`. A persistent failure is returned as `CatalogUnreachable` or `CatalogError`; an abort is not retried. This does not change Source write retries.
- Every product carries `version`, `publishedAt` and `sequence`; every offer `sequence` and `validUntil`.
- An offer of goods sold by measure carries `unitPrice`, the price in force per its Type's reference unit, such as `{ price: { amount: 1990, currency: "EUR" }, per: "kg" }` for 500 g at 9,95 €. It is worked out on every read, rounded to the minor unit half up, so it moves with a sale and needs no purge of its own. `per` is one of `kg`, `100g`, `l`, `100ml`, `m`, `m2`; goods sold by the piece have none.
- While a sale runs, an offer carries `lowestPrior`, the lowest price in force in the 30 days before the sale began, for the EU's price indication rule. It is taken from the prices shoppers were shown in those days, once the sale has begun: a sale recorded ahead of time gets it at its start, so it may appear up to one offer lifetime later. A product with no price in those days has none.
- A purge makes it fresher sooner. The lifetimes are the guarantee.
- Owned image responses, including HEAD and 304, answer `public, max-age=31536000, immutable` in browser and edge headers. Delivery resolves the current media digest, so replacement produces new URLs without waiting for an image lifetime. Old or wrong digests return an uncacheable 404 after replacement. Media tags still purge documents containing these URLs, not immutable image responses. Registered `/current` responses retain 30-second browser/edge lifetimes with explicit zero stale windows. CloudFront must respect these distinct policies without conflicting TTL overrides. Already-painted images do not refresh themselves, and document caching policies are unchanged. See [replacement freshness](/docs/catalog/media-storage#replacement-freshness).

Staff `GET /panel/media/{id}` includes `replacement: "in-place" | "owned-copy" | "none"` beside the file and its uses. `PUT /panel/media/{id}/owned-copy` takes new image bytes with the existing content-edit authority and adopts them at a registered file's ID without mutating the original. Ordinary `PUT /panel/media/{id}` remains managed-only. Digest deduplication and proportions apply to both. Repeating adoption with the same bytes is unchanged; different bytes after adoption conflict with `media_changed`. Sources cannot authorize or perform adoption.

`GET /v1/appointments/needs/{sku}` returns the complete effective `AppointmentNeeds` for one live SKU: its variant override, otherwise its Type default. `catalog.appointments.needs(sku)` returns `{ status: "found", needs }`, `appointments_off` or `appointments_not_taken`. Its offer-class lifetime is 30 seconds in the browser / 120 at the edge, clamped to the next scheduled version, with `settings`, `catalog` and the product's `p:` tags; it is not permission to book. Staff product handover is the uncached `POST /panel/products/{ref}/handover` management route, described in [Sync from a PIM or ERP](/docs/integrate/catalog-sources#staff-product-handover), as are the Type change's `POST /panel/products/{ref}/type/preview` and `POST /panel/products/{ref}/type` and an editor's withdrawal, `POST /panel/products/{ref}/publication` with `{ state: "withdrawn" | "live" }`.

## Category navigation tree

`GET /v1/category-tree?parent=&depth=&locale=` returns `{ object: "list", data: DeliveredCategory[] }`, with no pagination or truncation. The client's `categoryTree({ locale, depth: 2 })` reads a whole menu in one request; `categories({ parent, locale })` remains the paged one-level read.

`depth` is a positive integer, defaulting to two. Roots count as level one; with `parent`, its children count as level one and the parent itself is excluded. Categories are depth first, parents before children, siblings by position then creation order. Every row retains its full `path` and locale-aware `hasChildren`, including at the cutoff. Unpublished categories and branches whose ancestor did not release the locale are omitted. A parent that is not live returns `404 category_not_found`; a live parent unavailable in the locale returns an empty list. An unsupported locale returns `locale_unsupported`. Omitting `locale` uses the catalog default.

The answer uses the base lifetime (60 seconds in browsers, 600 at the edge), a weak ETag and conditional `304`. It carries every shown category's and ancestor's `c:` tag, `roots` when reading roots, and `catalog`, so publishing, renaming, moving or withdrawing a branch invalidates the menu as well as one-level reads.

## Category product presence

Use one native client read to decide which navigation categories contain live products of selected Types, including every visible descendant. No product pages, counts, prices or stock are read:

```ts
import { catalog } from "@orbcatalog/client";

export async function sellingCategories(url: string) {
  const shop = catalog({ url });
  const presence = await shop.categoryPresence({
    categories: ["outdoor", "angebote"],
    types: ["backpack", "jacket"],
    locale: "de",
    channel: "de",
  });
  return new Set(presence.data.filter((row) => row.hasProducts).map((row) => row.ref));
}
```

`GET /v1/category-presence?category=outdoor&category=angebote&type=backpack&type=jacket&locale=de&channel=de` returns `{ object: "list", data: [{ ref, hasProducts }], validUntil? }`. Category refs are deduplicated and sorted; Type keys are combined with OR. Unknown Types match nothing. Unknown, unpublished or locale-hidden categories answer `false`, as do their descendants when any ancestor is hidden. Products must be live, listed now and released in the requested locale; discontinued and withdrawn products never qualify. The Channel must exist and support the locale. It selects the storefront language, not an offer-availability condition: a live product needs no price or stock to qualify.

A request accepts 1–64 category refs and 1–32 Type keys. It traverses at most 64 ancestor levels and 1024 category memberships across the requested subtrees (overlapping subtrees count separately), with at most 800 distinct categories including ancestors and unknown requested refs so cache tags stay below Cloudflare's 16 KB header limit. Larger subtrees return `parameter_invalid`, never truncated answers; split the batch or select narrower categories. Existence checks use indexed listings and product rows and stop at a match, regardless of how many other Types precede it in a listing.

The base cache lifetime is 60 seconds in browsers / 600 at the edge. Every requested, descendant and ancestor category is tagged, including empty and unknown requested categories; normal product-publication, withdrawal and category-change purges invalidate affected answers. `schema` and `settings` tags cover Type-key and Channel changes. For a bounded indexed boundary read, the lifetime is conservatively clamped to the next scheduled product publication anywhere in the catalog, even outside the selected subtrees. The read evaluates scheduled versions at their time without waiting for settlement. `validUntil` exposes that same boundary to callers maintaining their own caches: never retain an answer or serve it stale beyond it. Purges accelerate freshness; the bounded lifetime is the guarantee. Independent application caches must consume invalidations or retain their own bounded freshness policy rather than assuming CDN purges evict application memory.

## Category subtree listings

By default, `products` lists only products linked directly to the selected category. Pass `descendants: true` to include its live descendants at every depth:

```ts title="src/category-products.ts"
import { catalog } from "@orbcatalog/client";

export async function categoryProducts(url: string, after?: string) {
  const shop = catalog({ url });
  return shop.products({
    category: "outdoor",
    descendants: true,
    locale: "de",
    channel: "de",
    limit: 20,
    after,
  });
}
```

The HTTP parameter is `descendants=true`; omitted or `false` keeps direct membership. Each product appears once, even when linked to the parent and a child or to several descendants. The selected category's pinned products lead in their pinned order; pins in descendants apply only to those categories' own listings. The rest follows first-publication time, newest first, with a stable product tie-breaker. One `next` cursor pages the entire result: pass it back as `after`, keeping the category and `descendants` unchanged.

Subtree answers carry every included category's cache tag, including empty descendants, so a product joining any of them purges the answer. Scheduled membership changes anywhere in the subtree clamp its lifetime. The usual locale and Channel rules, card `slug` and optional `offer` are unchanged.

## Product cards with prices

Every product card carries its localized `slug`; no URL parsing is needed. Pass `channel` to `products` or product `find` to include the card's `offer` in the same request:

```ts title="src/product-cards.ts"
import { catalog } from "@orbcatalog/client";

export async function productCards(url: string) {
  const shop = catalog({ url });
  return shop.products({ category: "outdoor/rucksaecke", locale: "de", channel: "de" });
}
```

The equivalent routes are `GET /v1/products?category=outdoor%2Frucksaecke&locale=de&channel=de` and `GET /v1/find?q=Alpin&kind=product&locale=de&channel=de`.

`offer` is the normal delivered offer, including its SKU, Channel, price, `compareAt`, sale window, unit price and availability. It belongs to the cheapest orderable variant of the published version; `limited`, `preorder` and `backorder` are orderable. If every priced variant is out of stock, it shows the cheapest one with `out_of_stock`. Equal prices keep published variant order. No price in force, a discontinued product or no `channel` means no `offer`. A Channel outside the current settings returns `channel_unsupported`.

These reads batch the page's offers internally; they spend only the listing or find miss budget, not one offer miss per card. With a Channel, the product-card answer uses the offer lifetime (30 seconds in the browser, 120 at the edge, or 10 seconds when it shows a limited offer), carries `offers` and each product's `op:` tag, and end at the next price step of **any** variant, including one whose future sale could become cheapest. Existing product and listing boundaries still apply. The card is a browsing hint: the offer read and OrbCart's quote remain authoritative at checkout. OrbPage's content cards are unchanged and carry no prices.

## The management client

The panel's routes under `/panel` are the staff side of the same contract: what an editor's panel reads and writes with a staff token. `@orbcatalog/client/staff` calls them the way the panel does, and the panel calls no catalog route by hand, so a change to a route breaks the panel and every other caller at compile time. Each call is parsed with the route's own schema, and a refusal is a value, never a throw.

```ts title="src/skis.ts"
import { staffCatalog } from "@orbcatalog/client/staff";

export async function jacketsToCheck(staffToken: string) {
  const catalog = staffCatalog({
    url: "https://catalog.example.com",
    fetch: (request) => {
      request.headers.set("Authorization", `Bearer ${staffToken}`);
      return fetch(request);
    },
  });

  const page = await catalog.grid({ search: "ski jacket", limit: 25 });
  if (!page.ok) throw new Error(page.problem.detail);
  return page.value.rows.map(({ ref, revision }) => ({ ref, revision }));
}
```

`fetch` is yours: it sends the staff token, and the admin's panel renews it once on a `401`. `catalog.product(ref)` reads a product with its draft, live version and owned fields, `catalog.history(ref)` its versions. A call answers `{ ok: true, value }` or `{ ok: false, problem }`. A catalog that does not answer, or answers something the client cannot read, is a problem of the client's own (`unreachable`, `unreadable`) with status `0`. A write takes an `Idempotency-Key`, so a retry lands once. Agents read through the [MCP endpoint](/docs/catalog/agents), which runs the same reads.