Cache API — Cachey

GET

/cache/:namespace/:id

Get cached item

Returns the cached value, remaining TTL, and expiry timestamp. Falls back to a shared entry if no tenant-specific item is found. Expired items are removed and treated as missing.

Response 200

{
  "value": "",
  "ttl": 295,
  "expiresAt": "2025-01-01T12:05:00.000Z",
  "shared": false
}

Status codes

200 — Item found
400 — Missing x-tenant-id
404 — Not found or expired

PUT

/cache/:namespace/:id

Set cached item

Creates or replaces a cached item.

Request body

Field	Notes
`value`	Required. Any JSON-serialisable value.
`ttl`	Optional. Seconds until expiry. Defaults to `CACHE_DEFAULT_TTL`.
`shared`	Optional. Allow other tenants to read as fallback. Default `false`.

Response 200

{
  "namespace": "articles",
  "id": "42",
  "ttl": 300,
  "expiresAt": "2025-01-01T12:05:00.000Z",
  "shared": false
}

Status codes

200 — Item stored
400 — Missing tenant, missing value, or invalid ttl

DELETE

/cache/:namespace/:id

Delete cached item

Removes a specific item. Idempotent — returns 200 even when no item exists. No response body.

DELETE

/cache/:namespace

Clear namespace

Removes all non-shared items in the given namespace for the requesting tenant.

Response 200

{
  "removed": 5
}

DELETE

/cache

Clear all tenant items

Removes all non-shared cached items for the requesting tenant across all namespaces.

Response 200

{
  "removed": 42
}