Title here
Summary here
管理 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:
| Endpoint | Method |
|---|---|
/healthz | GET |
/readyz | GET |
/drain | GET |
/version | GET |
/metrics | GET |
/v1/cluster/peers | GET |
Internal peer RPC endpoints (
/v1/peer/purge,/v1/peer/ban,/v1/peer/fetch,/v1/peer/metrics) are also auth-exempt. They are used for cluster-internal communication and not listed here.
Endpoints
| Endpoint | Method | Auth | Body | Response |
|---|---|---|---|---|
/healthz | GET | — | — | {"status":"ok"} |
/readyz | GET | — | — | {"status":"ready"} |
/readyz?detail=1 | GET | — | — | {"status":"...","conditions":[...]} |
/version | GET | — | — | {"version":"...","commit":"...","date":"..."} |
/drain | GET | — | — | {"status":"drained"} |
/metrics | GET | — | — | Prometheus text format |
/v1/cluster/peers | GET | — | — | Peer list JSON array |
/v1/purge | POST | ✓ | {"url":"https://example.com/a"} | {"status":"purged"} |
/v1/purge/batch | POST | ✓ | {"urls":["..."]} | {"status":"purged","count":N,"failed":N} |
/v1/ban | POST | ✓ | {"host_regex":"...","path_regex":"..."} | {"status":"banned","count":N} |
/v1/refresh | POST | ✓ | {"url":"https://example.com/a"} | {"status":"refreshed"} |
/v1/auth/check | GET | ✓ | — | {"status":"ok"} (only mounted when admin token is configured) |
/v1/cloudflare/status | GET | ✓ | — | Cloudflare status JSON (only mounted when Cloudflare is configured) |
/v1/stats | GET | ✓ | — | Runtime stats JSON (store entries, ring info, URL ring) |
/v1/config | GET | ✓ | — | Read-only JSON view of the running configuration |
/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/batchperforms 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.
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.