API Access and Plans

Public access, issued API keys, rate limits, Decisioning availability, and commercial packaging.

Public Access

The Philidor API is public for evaluation, research, and development. Anonymous requests receive 10 requests per 60 seconds per IP address.

First-party Philidor applications use a separate first-party budget of 60 requests per 60 seconds, so normal product traffic does not consume the anonymous public integration budget.

Keyless access is metered to discourage bulk scraping. List responses cap page size at roughly 100 rows, deep pagination beyond roughly 2000 rows requires a key, /changes is limited to a 30-day lookback, and a per-IP daily volume cap applies. Any API key removes these caps. Provide an API key for higher limits and full enumeration.

Public access covers all read endpoints listed in this reference, except limited-release Risk Graph endpoints that require an eligible key. Scores are public. Public decision verification remains available when the Risk Graph API is enabled.

curl https://api.philidor.io/v1/vaults?limit=5

API Keys

API keys are issued on request and are not self-serve. They use the pk_live_ format and are sent with the Authorization header.

curl -H "Authorization: Bearer pk_live_your_key_here" \
  https://api.philidor.io/v1/vaults?limit=100

Keys are bcrypt-hashed at rest. Each key has its own tier, per-key rate limit, and usage counter.

To request access, use the contact form.

First Call With an Issued Key

After receiving a key, make a small request and confirm that rate-limit headers are present.

curl -i \
  -H "Authorization: Bearer pk_live_your_key_here" \
  "https://api.philidor.io/v1/vaults?limit=1"

Look for HTTP/2 200, X-RateLimit-Limit, X-RateLimit-Remaining, and a JSON body with data.

Plans

Plan	Includes
Data	Scores, vault and asset registry, events and signals, baskets, exports, issued keys with elevated limits, and support
Decisioning	Everything in Data plus the Risk Graph family, portfolio look-through, pre-trade checks with signed decisions, breach and incident exposure, and basket webhooks
Embedded	Custom integrations, white-label data, contractual terms, custom webhooks, and custom limits

Decisioning capabilities are available by arrangement while the Risk Graph API is in limited release.

Keys are provisioned as data, decisioning, or embedded. Decisioning and embedded keys unlock Decisioning capabilities when enabled for the customer arrangement.

Support channels and service commitments are defined in each agreement. Embedded agreements can include uptime and support commitments.

Rate Limit Headers

Responses include rate limit information.

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in the window
`X-RateLimit-Reset`	Unix timestamp for window reset
`X-RateLimit-Window`	Window duration
`Retry-After`	Present on `429` responses

Anonymous Limits By Path

Path family	Anonymous limit
Public `/v1/*` routes	10 per 60 seconds
Portfolio `/v1/address/*`	10 per 60 seconds
Baskets read `/v1/baskets/*`	60 per 60 seconds
Graph reads `/v1/graph/*`	120 per 60 seconds
Graph check `/v1/graph/check`	60 per 60 seconds

401 and 403 Troubleshooting

Status	Common cause	Action
`401`	Missing bearer key on a gated route	Send `Authorization: Bearer pk_live_...`
`401`	Malformed or unknown key	Check the full key value and prefix
`403`	Key tier is below the endpoint gate	Request access for the required capability
`403`	Dashboard session lacks feature access	Check the active organization and plan

Fail-Safe Responses

Risk endpoints can return 503 when the platform is in fail_closed mode. These responses include Retry-After and X-Philidor-FailSafe-Mode.

Baskets Caching

Current basket routes return an ETag and use s-maxage=60 with stale-while-revalidate. Immutable version routes use Cache-Control: public, max-age=31536000, immutable.

If-None-Match returns 304 when the supplied ETag still matches.

Events Stream

GET /v1/events/stream is public and returns text/event-stream. The current implementation sends heartbeat comments every 20 seconds and allows up to 5 concurrent stream connections per IP.

const source = new EventSource('https://api.philidor.io/v1/events/stream');
source.addEventListener('published', (event) => {
  console.log(JSON.parse(event.data));
});

Event frames use published, promoted, or retracted.

Basket Webhooks

Basket webhook CRUD is available to decisioning and embedded keys.

Outbound deliveries include X-Philidor-Signature in this format.

t=<unix_ts>,v1=<hex>

Philidor signs the string timestamp.body with HMAC-SHA-256. Receivers should enforce a five-minute tolerance. Multiple v1 segments are accepted to support secret rotation. The signing secret is shown only at creation.

API Access and Plans

On this page