bouine Get started

Admin API

Authentication

All write endpoints require a bearer token. See Authentication for full details on token resolution, environment variables, and config file setup.

Pass the token in requests:

curl -X POST http://127.0.0.1:9000/v1/purge \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page"}'

Exempt endpoints (no token required)

These are always accessible without authentication — required for K8s probes and Prometheus scraping:

EndpointMethod
/healthzGET
/readyzGET
/drainGET
/versionGET
/metricsGET
/v1/cluster/peersGET

Internal peer RPC endpoints (/v1/peer/purge, /v1/peer/ban, /v1/peer/fetch, /v1/peer/metrics, and since v0.6.0 /v1/peer/config/hot and /v1/peer/keys/find) are also auth-exempt. They are used for cluster-internal communication and not listed here. Peer routes use strict JSON framing: unknown fields and trailing data are rejected.

Endpoints

EndpointMethodAuthBodyResponse
/healthzGET——{"status":"ok"}
/readyzGET——{"status":"ready"}
/readyz?detail=1GET——{"status":"...","conditions":[...]}
/versionGET——{"version":"...","commit":"...","date":"..."}
/drainGET——{"status":"drained"}
/metricsGET——Prometheus text format
/v1/cluster/peersGET——Peer list JSON array. On a local-mode daemon, answers 503 with the reason since v0.6.0
/v1/purgePOST✓{"url":"https://example.com/a"}{"status":"purged"}
/v1/purge/batchPOST✓{"urls":["..."]}{"status":"purged","count":N,"failed":N}
/v1/banPOST✓{"host_regex":"...","path_regex":"..."}{"status":"banned","count":N}
/v1/refreshPOST✓{"url":"https://example.com/a"}{"status":"refreshed"}
/v1/auth/checkGET✓—{"status":"ok"} (only mounted when admin token is configured)
/v1/cloudflare/statusGET✓—Cloudflare status JSON (only mounted when Cloudflare is configured)
/v1/statsGET✓—Runtime stats JSON (store entries, ring info, URL ring)
/v1/configGET✓—Read-only JSON view of the running configuration
/v1/config/hotGET✓—List hot-config knobs with live value and source (since v0.6.0)
/v1/config/hotPOST✓—Apply a validated hot-config point mutation (since v0.6.0); fans out to peers in strong mode
/v1/config/reloadPOST✓—Apply a config file to the running daemon (since v0.6.0, experimental, behind experimental.config_reload)
/v1/statusGET✓—Node overview: node, cache, origins, cluster, insights (since v0.6.0)
/v1/explain?url=...GET✓—Structured cache-decision tree for one URL (since v0.6.0)
/v1/keys/find?url=...GET✓—Cache state of a URL via a side-effect-free store probe (since v0.6.0)
/v1/keys/topGET✓—Most-requested URL prefixes with per-cache-result breakdown (since v0.6.0)
/v1/keys/recentGET✓—Most recently active URL prefixes (since v0.6.0)
/v1/debug/cachecheck?url=...GET✓—Cache debug info for a URL (key, hit/miss, source)
/debug/pprof/*GET✓—Go pprof profiling endpoints (only when admin.pprof_enabled: true)

Since v0.5.14, /v1/purge/batch performs a single local purge pass, one batched cluster fan-out for the whole batch (instead of one broadcast per URL), and per-URL Cloudflare propagation only for successfully purged entries.

Since v0.6.0, the new introspection and runtime-config endpoints (/v1/status, /v1/explain, /v1/keys/*, /v1/config/hot, /v1/config/reload) are documented in CLI with their matching bouine subcommands.

OpenAPI spec

A formal OpenAPI 3.0 specification is available at api/openapi.yaml in the repository. Use it with openapi-generator to produce SDKs in Python, TypeScript, and other languages.

Edit this page on GitHub
Prev
CLI
Next
Response headers