Skip to main content
Every /v1 request carries a Belief Systems API key. Keys look like belief_live_ followed by a secret, and are minted in the portal.

​
The two headers

Authorization: Bearer is the canonical form and the one every example in these docs uses.
Both carry the same secret and are accepted everywhere. Send one or the other, not both.

​
Keys belong on a server

/v1 answers cross-origin preflights only for Belief Systems’ own origins, so browser JavaScript on your domain will fail. Call it from your backend, which is also where the key belongs: a key shipped to a browser is a published key.
Non-production environments allow localhost, so a prototype that works against staging will not work in production. Treat the API as server-to-server from the start. There is no test mode and no sandbox host. The API is read-only, so a live key is safe to use in development.

​
Getting a key

Registration is free: work email, no password, a magic link. An account holds up to three active keys, so you can give staging and production their own and tell them apart by prefix in the usage view. The secret is displayed once, at creation, and is never retrievable. The system stores a hash, not the key. If you lose it, rotate.

​
Rotation and revocation

  • Rotation issues a new secret and retires the old one in the same operation. The old secret stops working immediately. Usage history stays with the account.
  • Revocation takes effect immediately. Every subsequent call returns invalid_api_key.
  • Snapshot file downloads validate keys against a one-minute cache, so a revoked key can still open a snapshot file for up to a minute afterward. The API itself does not wait.
Both operations are in the portal, alongside per-key usage.

​
Metering is per key

Rate limits are counted per key, not per IP, so two keys never spend each other’s quota. GET /v1 reports the limits actually in force for the calling key, beside what is left of each window.
Rate limits and the history window are access controls under the Terms of Service. Spreading requests across several keys or accounts to exceed them is prohibited. Sustained or production volume is covered by Index Services.
Calls made through the MCP server draw on the same two windows as direct API calls.