Documentation

Errors

Every error is {"error":{"code":"…","message":"…"}} with a machine-stable code. The shared shapes below apply to all api-key endpoints; per-endpoint errors are listed on each page.

shared

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"missing or invalid api key"}
402quota_exceeded{"code":"quota_exceeded","message":"monthly quota exceeded","upgrade_url":"/pricing"}
403forbidden_scope{"code":"forbidden_scope","message":"missing required scope: memory:read"}
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}

POST /v1/read

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid url"}
502fetch_failed{"code":"fetch_failed","message":"upstream returned 404"}
504fetch_timeout{"code":"fetch_timeout","message":"deadline exceeded"}
StatuscodeExample
400bad_request{"code":"bad_request","message":"query is required"}
502fetch_failed{"code":"fetch_failed","message":"all search routes failed"}

POST /v1/research

StatuscodeExample
400bad_request{"code":"bad_request","message":"question is required"}
502fetch_failed{"code":"fetch_failed","message":"all search routes failed"}

POST /mcp

StatuscodeExample
401-32001{"code":-32001,"message":"invalid api key"}
403-32003{"code":-32003,"message":"missing required scope: memory:write"}
405method_not_allowed{"code":"method_not_allowed","message":"POST only — MCP speaks JSON-RPC over POST"}

POST /v1/memory/write

StatuscodeExample
400bad_request{"code":"bad_request","message":"text normalizes to empty — nothing to store"}
StatuscodeExample
400bad_request{"code":"bad_request","message":"query normalizes to empty — nothing to match"}

DELETE /v1/memory/:id

StatuscodeExample
404not_found{"code":"not_found","message":"memory item not found"}

POST /auth/signup

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid email"}
409bad_request{"code":"bad_request","message":"email already registered"}
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}

POST /auth/login

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"invalid credentials"}
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}

POST /auth/verify-email

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid or expired token"}

POST /auth/forgot-password

StatuscodeExample
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}

POST /auth/reset-password

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid or expired token"}

GET /me

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}

POST /keys

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}
403email_not_verified{"code":"email_not_verified","message":"verify your email before creating keys"}
403forbidden_scope{"code":"forbidden_scope","message":"scopes outside your plan: memory:read"}

GET /keys

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}

DELETE /keys/:id

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}
404not_found{"code":"not_found","message":"key not found"}

POST /billing/checkout

StatuscodeExample
401unauthorized{"code":"unauthorized","message":"login required"}
400bad_request{"code":"bad_request","message":"unknown plan"}
503internal{"code":"internal","message":"billing_not_configured"}

POST /billing/webhook

StatuscodeExample
400bad_request{"code":"bad_request","message":"invalid webhook signature"}