Skip to content

Caching semantics for an integrator

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

NameTypeDefaultDescription
AX surfacespublic, max-age=3600—

/llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt. The value is ax.cacheTtl.

Image variantspublic, max-age=31536000—

/media/:id/variant/:name and /media/:id/resize — derived bytes, addressed by a key that changes when the derivation does.

Original media(none)—

/media/:id/file and /media/:id/original send no caching header at all.

Everything else(none)—

Content, feeds, search, nav, menus, GraphQL, the Markdown projection and /ax/status.

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.

the key namespaces, all site-prefixedtext
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}

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 two admin controls

GET/api/v1/cache/status?siteId=<site>Site admin

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.

200
{
  "data": {
    "provider": "memory",
    "ttl": { "default": null, "content": null, "feed": null, "nav": null },
    "entries": 0
  }
}
POST/api/v1/cache/clearSite admin

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.

200
{ "data": { "cleared": true, "entries": 0 } }

Running these as an operator rather than calling them is Cache administration; the AX surfaces' own TTL and headers are AX surfaces as a machine-readable feed.