Skip to content

Cache administration

Two siteAdmin routes report the cache provider with its TTLs and clear every entry; the default in-memory provider is per process, not per deployment.

Two routes, both siteAdmin, and that is the entire cache surface: read the provider and its TTLs, or throw everything away. Neither is something to run on a schedule.

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

The provider name and TTLs come straight from config.cache; a null TTL means the config omitted it and the reading layer's own fallback applies. entries is a live count where the provider can report one cheaply — see below for when it can't.

200
{
  "data": {
    "provider": "memory",
    "ttl": { "default": null, "content": null, "feed": null, "nav": null },
    "entries": 0
  }
}
POST/api/v1/cache/clear?siteId=<site>Site admin

Invalidates every key the provider holds, then reports the resulting count. Takes no body.

200
{ "data": { "cleared": true, "entries": 0 } }
bash
curl -s -H "Authorization: Bearer $KYWI_ADMIN_TOKEN" \
  "https://example.com/api/v1/cache/status?siteId=default"

curl -s -X POST -H "Authorization: Bearer $KYWI_ADMIN_TOKEN" \
  "https://example.com/api/v1/cache/clear?siteId=default"

Without a credential both answer {"error":{"code":"UNAUTHORIZED","message":"Unauthorized"}}; with one below siteAdmin, FORBIDDEN. A siteAdmin API key works as well as a user token.

TTLs are config, so changing one is a deploy

status echoes the cache block of kywi.config.ts — there is no route that writes a TTL and no setting in the admin that shadows it. A project with no cache block reports all four as null, which means "unset", not "no expiry": each cached read applies its own fallback. Which reads are cached, under which keys, and what those fallbacks are is Caching semantics for an integrator.

Read entries, not provider, to know what you are running

provider is the configured value, not the constructed object, and the two can disagree. Core builds a Redis provider only when the host application constructs the API handler itself and hands it a Redis client; the Next runtime that a scaffolded project boots on does not, so it runs the in-memory provider whatever config.cache.provider says. status will still report "redis".

entries is the honest signal. The in-memory provider counts its map, so you get a number. Redis cannot count cheaply, so it reports null — which is not an error and not an empty cache. A number means memory; null means Redis.

Clearing is all-or-nothing

The route matches every key, with no per-key, per-type or per-site scoping — see Caching semantics for an integrator for the blast radius on a deployment hosting several sites.

When you actually need it

Ordinary writes invalidate themselves: publishing, updating, deleting, restoring and the bulk routes all fire cache invalidation on the way through, so an editorial change is visible on the next request without anyone touching this. Reach for clear only when content changed outside that path and no hook fired — after a hand-written SQL patch, after a database restore, after a direct import. Clearing on a timer is a sign the TTLs are wrong, not the cache.