Skip to main content

Admin API

The Admin API runs on a separate port (default 127.0.0.1:4001) and exposes endpoints for health checks, cache management, rendering, and metrics.

Authentication​

All endpoints except GET /health require a bearer token when admin.bearer_token is configured in prism.toml:

[admin]
address = "127.0.0.1:4001"
bearer_token = "your-secret-token"

Include the token in the Authorization header:

Authorization: Bearer your-secret-token

Token comparison uses constant-time equality to prevent timing attacks.

Endpoints​

GET /health​

Returns the health status of the PRISM instance. No authentication required.

Returns 200 when Chrome is responsive, 503 when unhealthy.

curl http://127.0.0.1:4001/health
{"status": "ok"}

Unhealthy response (503):

{"status": "unhealthy", "reason": "chrome not responding"}

GET /status​

Returns runtime statistics including uptime, cache state, pool size, and render counts.

curl -H "Authorization: Bearer your-secret-token" \
  http://127.0.0.1:4001/status
{
  "uptime_secs": 3600,
  "cache": {
    "entries": 1482,
    "memory_bytes": 52428800
  },
  "pool": {
    "size": 8,
    "available": 5,
    "crashes": 0
  },
  "renders": {
    "total": 4521,
    "active": 3,
    "queue_depth": 0
  }
}

GET /metrics​

Returns all metrics in Prometheus text exposition format (text/plain; version=0.0.4).

curl -H "Authorization: Bearer your-secret-token" \
  http://127.0.0.1:4001/metrics
# HELP prism_requests_total Total requests by cache status
# TYPE prism_requests_total counter
prism_requests_total{status="hit"} 3200
prism_requests_total{status="miss"} 1321
...

See the Metrics Reference for a full list of exported metrics.

POST /purge/url​

Purge a specific URL from the render cache.

curl -X POST \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"url": "/products/widget-pro"}' \
  http://127.0.0.1:4001/purge/url
{"purged": true}

The purged field is true if the URL was found and removed, false if it was not in the cache.

POST /purge/pattern​

Purge all cached URLs matching a glob pattern.

curl -X POST \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"pattern": "/products/*"}' \
  http://127.0.0.1:4001/purge/pattern
{"purged_count": 47}

POST /purge/all​

Purge the entire render cache.

curl -X POST \
  -H "Authorization: Bearer your-secret-token" \
  http://127.0.0.1:4001/purge/all
{"purged_count": 1482}

POST /render​

Force-render a URL through the Chrome pipeline and store the result in cache. Requires a valid license.

curl -X POST \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"url": "/products/widget-pro"}' \
  http://127.0.0.1:4001/render

Success response:

{
  "status": "ok",
  "cache_status": "MISS",
  "render_time_ms": 1250,
  "html_bytes": 48230
}

Error responses:

  • 403 — No valid license: 
    {"error": "rendering unavailable — license required"}
  • 400 — Invalid URL or path traversal attempt
  • 500 — Render failure (Chrome crash, timeout, etc.)

The url field accepts either a path (/page) or a full URL (https://example.com/page). Full URLs are parsed and only the path and query string are used.

POST /warmup​

Start a cache warmup job by fetching and rendering all URLs from a sitemap. Requires a valid license.

curl -X POST \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"sitemap_url": "https://example.com/sitemap.xml"}' \
  http://127.0.0.1:4001/warmup
{"status": "warmup started"}

Returns 202 Accepted on success, 409 Conflict if a warmup is already in progress.

GET /warmup/status​

Check the progress of a running warmup job.

curl -H "Authorization: Bearer your-secret-token" \
  http://127.0.0.1:4001/warmup/status
{
  "status": "running",
  "total": 500,
  "processed": 237,
  "errors": 3,
  "elapsed_secs": 45.2,
  "error_message": null
}

The status field can be idle, running, or completed.

Error Handling​

All error responses use JSON:

{"error": "description of what went wrong"}

Common status codes:

CodeMeaning
400Invalid JSON body or bad request
401Missing or invalid bearer token
403License required for this endpoint
404Unknown endpoint
409Conflict (e.g., warmup already running)
500Internal server error

Request bodies are limited to 1 MB.