API Overview

Base URL

https://api.philidor.io

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

Authentication

No API key required for public read endpoints. Admin endpoints require JWT authentication (not publicly available).

Rate Limits

Rate limit headers are included in responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Response Format

All responses use a standard envelope:

{
  "success": true,
  "data": { ... }
}

Paginated responses include pagination metadata:

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

Error Format

{
  "success": false,
  "error": {
    "message": "Vault not found",
    "code": "NOT_FOUND"
  }
}

HTTP status codes: 200 (success), 400 (bad request), 404 (not found), 429 (rate limited), 500 (server error).

Caching

Redis-backed HTTP caching with varying TTLs:

Cache headers (Cache-Control, ETag) are included in responses.

Endpoints