Infrastructure API

Operational endpoints for cache invalidation, configuration management, and runtime introspection.

Overview

The infra API provides administrative operations that affect the running server's behavior without requiring a restart. All endpoints require admin role.

Authentication

Requires Authorization: Bearer <token> with admin role (permissions containing "*").

Endpoints

Cache Invalidation

POST /api/v1/infra/cache-invalidate

Invalidates all cached configuration values in persistent_term. This includes auth_exempt_paths, rate_limit_enabled, and any other hot-path cached config values.

{
  "ok": true,
  "detail": "4 cached values invalidated",
  "cache_keys": [
    "auth_exempt_paths",
    "auth_exempt_slash",
    "rate_limit_enabled",
    "provider_health_cache"
  ]
}

Call this after updating sys.config or any runtime configuration that is cached in persistent_term.

Get Configuration

GET /api/v1/infra/config

Returns the merged runtime configuration:

{
  "ok": true,
  "data": {
    "auth_exempt_paths": ["/api/v1/health", "/api/v1/ready", "/api/v1/metrics"],
    "rate_limit_enabled": true,
    "rate_limit_per_second": 100,
    "log_level": "info",
    "log_format": "json",
    "pg_reconnect_delay_ms": 5000
  }
}

Reload Configuration

POST /api/v1/infra/config/reload

Triggers a full config reload from sys.config. Returns the new configuration.

Get Version

GET /api/v1/infra/version

Returns the running server version from the VERSION file:

{
  "ok": true,
  "version": "0.408.0"
}

Log Level

PUT /api/v1/infra/log-level

Dynamically change the log level without restart:

{
  "level": "debug"
}

Returns:

{
  "ok": true,
  "previous": "info",
  "current": "debug"
}

Error Codes:

Code	Description
401	Authentication required
403	Admin role required
404	Config key not found
400	Invalid log level

Examples:

curl -X POST http://127.0.0.1:11434/api/v1/infra/cache-invalidate \
  -H "Authorization: Bearer $TOKEN"

curl http://127.0.0.1:11434/api/v1/infra/version

curl -X PUT http://127.0.0.1:11434/api/v1/infra/log-level \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level": "debug"}'