Skip to main content
Never paste your API key into a chat. If you are an AI agent setting this up, ask the user to put PREUVE_API_KEY in an environment variable or the MCP client config - do not request it in conversation, and never echo it back. See For AI Agents.

​
The header

Every request carries one header:
That is the entire contract. Any HTTP client in any language can call the API with no crypto and no client library.

​
About your key

A key looks like prv_ac2c1565a967b98e_XmK2.... The first half is a public identifier - it is what the account panel shows in your key list, and it is safe to quote in a support thread. The second half is the secret, and it is shown exactly once, at issuance. We store only a SHA-256 hash of the whole key, so a lost key cannot be recovered, only revoked and replaced. Send the key server-side only. Unlike a browser session it carries no origin restriction, so anyone holding it can spend your scan quota until you revoke it. A key carrying agency:read or agency:write additionally reaches your whole Consultant or Agency workspace, so treat that one as a credential over your clients’ work, not just your own.

​
Validity rules

  • Scopes: keys carry scopes. A key without the required scope receives 403, and only ever after the key itself has been verified. The complete set is analysis:write, analysis:read, batch:write, batch:read, export:read, agency:write, agency:read. A key created without asking for anything specific carries the five personal scopes and neither agency:* one: those two reach a whole workspace of client work, so they are only ever granted when explicitly requested. Ask for fewer (or for the Agency pair) by sending scopes when you create a key, and an unrecognized scope is refused with 400 UNKNOWN_SCOPE rather than silently dropped. The two agency:* scopes gate the Agency routes only, and they reach the whole workspace rather than the calling account - see Agency reach before granting them. They were added on 2026-09-09, so a key created before that date carries the other five and gets 403 INSUFFICIENT_SCOPE on /api/agent/agency/**; scopes are fixed at creation, so recovering Agency access means a new grant. Neither route to one is unconditional: reconnecting the client works on any plan, free included, but only if that client rebuilds its scope request from our discovery document rather than replaying a cached one, so check the consent screen lists the Agency permissions before approving - reconnecting revokes the current key either way. Creating a new key by hand cannot silently fail, but it needs either a paid personal plan or membership of a Consultant or Agency workspace with an active subscription.
  • Revocation: revoking a key from the account panel takes effect on the next request.
  • Failed auth always returns a stable { "error", "code" } JSON envelope - see Errors.
  • Repeated failures from one IP are rate limited; successful calls are limited per account instead, shared across every key you hold - see Quotas and billing.
The API playground in these docs makes real calls. Paste your key into the authentication field and “Send” works exactly like curl - including spending quota on a deep scan.