# Caching semantics for an integrator

URL: https://kywi-docs-production.up.railway.app/integrating/caching-semantics-for-an-integrator
Type: docPage

Caching is server-side and hook-invalidated: JSON responses send no validators, and only AX surfaces and image variants carry a `Cache-Control` header.

Kywi caches inside the server, keyed by site, and clears on the event rather than on a clock. Almost none of that reaches the wire, so a client's caching strategy is its own to design — this page is what the API will and will not tell you.

## The API sends no validators

No JSON response carries an `ETag` or a `Last-Modified` — neither header exists anywhere in core, so a conditional request is not a supported optimisation: `If-None-Match` is ignored and you will get a 200 with a full body every time. `Cache-Control` does exist, but only on the two families of response in the table below — everything else sends none of the three. Poll on your own interval, or subscribe to [webhooks](/integrating/webhooks/) and stop polling.

## Where a Cache-Control header actually appears

Only two families of Kywi response carry a Cache-Control header: the AX surfaces and the derived image representations. Note the asymmetry in media — the year-long header is on the variant and resize routes, not on the original file, so a CDN in front of Kywi will happily hold a thumbnail for a year and re-fetch the full-size original on every request.

## What the server cache holds

The provider is in-memory or Redis, and every key is prefixed with the site it belongs to. The namespaces are fixed: a node by id and by slug, feeds by slug and by hashed query, the nav tree by root and depth, named menus, and the resolved site config, plus one entry per AX surface.

content:{siteId}:{id} content:{siteId}:{type}:{id} content:{siteId}:slug:{slug} content:{siteId}:{type}:slug:{slug} feed:{siteId}:{feedSlug} feed:{siteId}:query:{md5-of-sorted-query} nav:{siteId}:{rootId}:{depth} menu:{siteId}:{menuSlug} site:{siteId}:config ax:{siteId}:{surface}

## the key namespaces, all site-prefixed

TTLs come from the `cache` config block — `contentTtl`, `feedTtl`, `navTtl` — and each falls back to 300 seconds when unset; AX falls back to 3600. A cached read is not a thinner read: the content getters re-fetch joined with the content type's custom-field table before storing, so a cache hit returns the same base-plus-custom shape an uncached one does, custom fields included.

## Freshness is driven by the event, not the TTL

One content mutation clears five things at once: that node's id key, its slug key, and every `feed:`, `nav:` and `ax:` entry for the site. Publish, unpublish, update, layout save, delete, trash restore and permanent delete all fire it, and the bulk routes dispatch the same hooks once per affected row. So a consumer sees an editorial change on the next request rather than up to five minutes later — the TTL is the ceiling for a site nobody is editing, not the propagation delay after an edit.

## The menu cache namespace has no shipped reader

Menus are read straight from the database on every request — `scope.menus.getResolved` calls `resolveMenu` directly, no cache in between, so a re-slug shows immediately. Menu writes still invalidate `menu:{siteId}:*` and `nav:{siteId}:*` on every mutation — that plumbing exists for `createCachedMenuQueries`, an exported cache wrapper nothing in this codebase calls.

A host that wires it in front of its own menu reads inherits real staleness: the cached tree bakes in each item's `href`, resolved from the linked content row's `path` at cache-set time, so re-slugging the target page clears that content's own cache entries but leaves the cached menu untouched until TTL or an unrelated menu write clears it.

## The two admin controls

The configured provider and TTLs, plus a live entry count. A `null` TTL means the config omitted it and the 300-second fallback applies; `entries` is null on a provider that cannot count cheaply, which is what Redis reports.

Invalidates everything the provider holds and reports the resulting count. Use it after a change made outside Kywi — a direct database write, a restore — that fired no hooks.

## Clearing is deployment-wide, not per site

Despite being a siteAdmin action, `POST /cache/clear` takes no site and matches every key. On a deployment hosting several sites, one site's admin clearing their cache cold-starts every other site's content, feeds, nav and AX surfaces too. On a busy install that is a real load spike, not a no-op.

Running these as an operator rather than calling them is [Cache administration](/operating/cache-administration/); the AX surfaces' own TTL and headers are [AX surfaces as a machine-readable feed](/integrating/ax-surfaces-as-a-machine-readable-feed/).
