API Key Configuration

Per-key defaults, restrictions, and idempotency.

Per-key settings

Each API key can be configured with defaults and restrictions via Dashboard → API Keys → Settings or PATCH /api/dashboard/keys/:id.

Setting	Type	Effect
defaultFilters	string[]	Filters applied to every request (merged with per-request filters)
spendLimitCents	number	Hard all-time spend cap in cents. Returns 402 once reached
maxTokensPerRequest	number	Silently caps `max_tokens` if the caller requests more
allowedTaskTypes	string[]	Restrict key to specific task types. Returns 403 for others
allowedModels	string[]	Whitelist of model IDs. Returns 403 if router picks another
deniedModels	string[]	Blocklist of model IDs. Returns 403 if router picks a blocked model
description	string	Internal label (max 500 chars) — visible only in dashboard

Idempotency

For non-streaming requests, pass an Idempotency-Key header (or X-Idempotency-Key) to safely retry without double-billing.

curl https://api.pathfinder.dev/v1/chat \
  -H "Authorization: Bearer pf_live_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: req_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [{ "role": "user", "content": "Hello" }] }'

Scope: keys are scoped per API key (two different keys can use the same idempotency value independently).

TTL: cached responses expire after 24 hours.

Replay: if a match is found, the cached response is returned with X-Idempotency-Replayed: true. Replayed requests skip rate limiting and balance checks.

Streaming: idempotency is not available for streaming requests.