Authentication & keys

Every /v1/* endpoint requires an API key sent as a bearer token:

curl -X POST https://api.aptrouter.com/v1/search \
  -H "authorization: Bearer sk_live_…" \
  -H "content-type: application/json" \
  -d '{"query":"quantum error correction surface codes"}'

Only GET /health is unauthenticated.

Keys and the dashboard

Keys are issued per customer and managed from the aptrouter.com dashboard:

• Minting. Create a key from the dashboard. The sk_live_… secret is shown once, right after you create it — only its hash is stored server-side, so copy it then. Lost a secret? Rotate via support.
• Usage. The dashboard shows your active key (by hash prefix), your current prepaid credit balance, and requests/credits used to date, plus a button to top up. You can also check usage programmatically with GET /v1/usage — it’s free to call.
• Secrecy. Treat keys like passwords: environment variables or a secret manager only, never source control, never client-side code.

Metering

Billing is prepaid — no subscription, no plans, no free tier. POST /v1/search debits 1 credit ($0.005, i.e. $5 per 1,000 searches) from your balance; internal errors and timeouts are automatically refunded. When your balance hits zero the API returns 402 — top up in the dashboard to resume.

curl https://api.aptrouter.com/v1/usage \
  -H "authorization: Bearer $APTROUTER_API_KEY"
# → { "period": "2026-06", "requests": 4213, "credits": 4213, "balance": 5787 }

Usage & balance headers

Successful (200) search responses carry headers so an agent framework can budget without parsing the body:

Header	Meaning
X-Token-Budget	Estimated token count of the response body (~4 chars/token)
X-Credit-Balance	Prepaid credits remaining after this call

A 429 (rate-limit) response instead carries RateLimit-Limit (your requests-per-minute cap) and Retry-After (seconds to wait before retrying).

Error codes

Status	Meaning
400	Empty query, or query longer than 2048 characters
401	Missing, invalid, or revoked API key
402	Prepaid balance exhausted — zero credits (X-Credit-Balance: 0). Top up to resume
429	Per-key burst rate limit or too many concurrent requests — honour Retry-After
500	Internal error — the charged credit is automatically refunded
504	Search exceeded the per-request timeout — credit refunded

Full response schemas are in the API reference.