API Overview

Public REST API base URL, access model, response format, pagination, caching, and endpoint families.

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

Access type	Limit	Key required
Public	30 requests per 60 seconds per IP	No
API key	Per-key `rate_limit_rpm`	Yes

Rate limit headers include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Window. A 429 response includes Retry-After.

To request a key, 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"
  }
}

Common HTTP status codes are 200, 400, 401, 403, 404, 429, 500, and 503.

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.

Endpoints

Family	Description
Vaults	List, search, batch lookup, scores, and change polling
Vault Detail	Single vault detail, snapshots, score history, holders, markets, strategies, and vault events
Protocols	Protocol information
Curators	Curator information
Events	Event feed, detail, group representative lookup, and SSE stream
Signals	News and risk signals
Security Events	Broad published security-event registry feed
Portfolio	Address position analysis
Chains	Supported chains
Assets	Asset symbols and enriched asset registry
Baskets	Reference baskets, versions, changes, methodology history, and webhooks
RWA	Real-world-asset registry and institutional metadata
Stats	Platform statistics
Oracle	Oracle freshness data
Risk Graph	Limited-release Decisioning family and public snapshot manifests
Research	Research transparency and preview artifacts
Royco	Royco Dawn market integration
Reviewers	Methodology reviewer roster
Methodology	Public methodology version and asset-weight registry
Health	API health check

Additional live public routes include /v1/vaults/scores, /v1/vaults/changes, /v1/vaults/batch, /v1/curators/{id}/events, and /v1/graph/snapshot/{id}.

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