# Cache administration

URL: https://kywi-docs-production.up.railway.app/operating/cache-administration
Type: docPage

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.

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.

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

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](/integrating/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.

## An in-memory clear only clears the container that answered

The default provider is a plain `Map` in one Node process. On a deployment running more than one container — or one that scales to more under load — a `POST /cache/clear` lands on whichever instance the load balancer picked and leaves every other instance's cache untouched. There is no fan-out. Clearing "worked" and stale content still being served is the expected outcome, not a contradiction; call it once per instance, restart the service, or run Redis — which needs a host app that constructs its own Redis-backed provider, since the scaffolded Next runtime does not wire one in (see above).

## 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](/integrating/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](/operating/applying-a-hand-written-schema-patch-outside-kywi-migrate/), after a database restore, after a direct import. Clearing on a timer is a sign the TTLs are wrong, not the cache.
