API Overview

Base URL

https://api.philidor.io

All endpoints are under /v1. OpenAPI spec is available at /v1/openapi.json. Swagger UI is available at /v1/docs.

Authentication

No API key is required for public read endpoints. Issued keys provide per-key limits and plan-specific capabilities. See API Access and Plans.

Rate Limits

Windows are fixed 60-second windows. Rate limit headers include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Window; a 429 response includes Retry-After. The full header list, the per-family budgets and the shared-key rules are in API Access and Plans.

Organisations on a plan mint their own keys in the dashboard; to obtain a plan, use the contact form.

Response Format

Most responses use a standard envelope.

{
  "data": { ... }
}

Paginated responses include metadata.

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 247,
    "totalPages": 25
  }
}

Cursor-style pages use hasMore instead of a total.

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 20,
    "hasMore": false
  }
}

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Vault not found",
    "request_id": "3f6c1a2e-9b7d-4c1e-8f2a-1d2e3f4a5b6c"
  }
}

Every error uses one nested error object with {error:{code,message,request_id}}, including the retired-version 410. Error responses use Cache-Control: no-store to prevent replaying a request id. During the one-release code migration, responses that previously used a lowercase code also include error.legacy_code; the complete table and retry guidance are in Errors. Every response carries X-Request-Id.

Common HTTP status codes are 200, 400, 401, 403, 404, 429, 500, 503 and 504 (a read that exceeded its 60-second deadline; retry after Retry-After).

Caching

Cache headers vary by endpoint. Basket current-version routes return ETag with s-maxage=60 and stale-while-revalidate. Immutable basket version routes use one-year immutable cache headers. Cached public reads carry X-Cache and Age; when a fresh read fails, the last good copy is served with X-Cache: STALE-ERROR and Warning: 111 rather than an error.

Platform Status

GET /v1/status (no key, cached 60 seconds) reports the platform's health for your dashboards: status (the worst of the loopback heartbeat, off-box reachability and the 5xx rate), a rollup across every component including the event stream, webhooks and data freshness, a components[] list with a detail line per component, the raw signals, and rolling uptime. GET /ready answers 200 only when the database answers. See Health.

Endpoints

Additional live routes include /v1/vaults/batch, /v1/curators/{id}/events, and /v1/graph/snapshot/{id} (public), plus /v1/vaults/scores and /v1/vaults/changes (Data key) — see API Access and Plans.

Admin and dashboard routes exist for private product operations. They are excluded from the public OpenAPI spec.