Server Utils

Docus Plus includes two server utilities: cache management endpoints and public health endpoints. Use them to invalidate generated content safely and to give your platform a meaningful readiness probe.

Configure cache storage

The cache module manages Nitro's cache storage mount. Its driver is selected by the active runtime, so the layer supports a deliberately limited set of storage options:

You cannot select another Nitro or Unstorage driver for this cache mount. The module adds metadata to every supported driver so it can invalidate cache entries by page path.

For a Node deployment, configure Redis or Valkey using one connection URL:

REDIS_URL=rediss://default:[email protected]:6380

Alternatively, provide REDIS_HOST, REDIS_USERNAME, and REDIS_PASSWORD; REDIS_PORT, REDIS_DB, REDIS_TLS, and REDIS_TLS_REJECT_UNAUTHORIZED are optional. A REDIS_URL takes precedence over those individual values. See Deployment for the complete runtime-specific setup.

Manage cache entries

The module exposes the following admin routes. Each response is wrapped as { data: ... }.

Protect every cache request with either an x-admin-token header or a Bearer token. The module uses cache.apiToken, then runtimeConfig.apiToken, then API_TOKEN as its token source.

curl \
  --header "x-admin-token: YOUR_API_TOKEN" \
  https://docs.example.com/api/_cache/keys

Cache keys returned by the list route are mount-local, such as pages:article-one. Read and delete routes also accept the fully-qualified form, such as cache:pages:article-one.

To connect a CMS webhook to targeted invalidation, map each collection to the cache base key and the field that contains its route segment:

export default defineNuxtConfig({
  cache: {
    cacheMap: {
      articles: {
        key: "pages:articles",
        fieldKey: "slug",
        pathPrefix: "/articles"
      }
    }
  }
});

The flush endpoint uses this mapping and the path metadata stored with cache entries. If no cacheMap is configured, it cannot determine which entries a CMS event should remove.

Add health probes

Use GET /api/system/ping as a lightweight liveness check. It is public, unauthenticated, and returns plain-text pong.

Use GET /api/system/health as a readiness check. It writes, reads, and removes a short-lived value from the same cache storage used by the application. The route is also public and returns a wrapped JSON response with an overall status, timestamp, and cache component timing.

{
  "data": {
    "status": "ok",
    "timestamp": "2026-07-16T09:00:00.000Z",
    "components": {
      "cache": {
        "status": "ok",
        "responseTimeMs": 12
      }
    }
  }
}

When the cache probe fails, the health route responds with HTTP 503. You can also mark slow cache storage as degraded or unhealthy by setting response-time thresholds:

export default defineNuxtConfig({
  healthcheck: {
    cache: {
      threshold: {
        warn: 50,
        error: 200
      }
    }
  }
});

At or above warn, the cache component and overall status become warn; at or above error, they become error and the endpoint returns 503. Docus Plus disables route caching and prerendering for both the cache and system endpoint paths.