Skip to main content
This page is written for the agent itself: if you are an AI agent working with the Preuve Agent API or MCP server, follow these rules.

​
Reading these docs programmatically

​
Getting in

Start free: connect and run your first starter scans.
  • A key costs nothing to obtain. Connecting the MCP server from any client mints one over OAuth on a free account. Creating one by hand in Account → API Keys needs a paid personal plan or membership of a Consultant or Agency workspace with an active subscription - see Authentication.
  • scanType: "starter" is the sandbox. There is no separate sandbox host or test key: starter runs hit the same endpoints, return the same { error, code } errors and the same response envelope, and cost nothing. What differs is depth, not shape - a starter run reports modules: null while polling, and its export omits the deep-only sections (each one is named in the report’s details.omitted). Explore with starter, then switch the one field when the user asks for the full report.

​
Agent guidance rules

  1. Prefer the MCP server when it is connected. Fall back to plain HTTP with the x-preuve-key header (HTTP API) - there is no client library to install. If you can load skills, install the Agent Skill - it encodes everything on this page plus the full workflow.
  2. scanType is always an explicit choice. "starter" costs nothing; "deep" consumes the user’s paid quota. Never run a deep scan the user did not ask for.
  3. Reuse the same clientRunId to retry. Retries never double-spend; a run that already started returns its stored outcome instead of running again.
  4. Poll, don’t hammer. Starter scans complete in about a minute, deep scans in about eight. Poll every 10-30 seconds and back off on 429 - RATE_LIMITED and CONCURRENT_LIMIT_REACHED are retryable with the same clientRunId.
  5. Branch on code, not on error messages. Every error is a stable { error, code } envelope - see Errors.
  6. Do not expose secrets in chat. Never ask the user to paste PREUVE_API_KEY into a conversation, and never echo it back. Prefer environment variables or the MCP server config.
  7. Do not pass publish: true unless the user explicitly wants a public share link. Runs are private by default.
  8. Deep modules are capped at one successful generation per module per report. A 409 MODULE_ALREADY_GENERATED means the payload already exists - read it from the export instead of retrying.

​
What a key can and cannot do

A Preuve API key is a scoped analysis credential, not an account login. If a key leaks, the user revokes it and no personal report it did not create is exposed.

​
On an Agency account the reach is wider

Read this before treating a key as a low-value credential. When the owning account belongs to a Consultant or AppSumo Agency workspace, a key carrying an Agency scope also reaches the Agency workspace calls, and those are scoped to the workspace, not to the key. There are two Agency scopes, they are enforced per route, and neither implies the other, so read each row against the scope it names rather than against “has an Agency scope”: A read-only key cannot start anything, and a write-only key cannot list, poll or export a single report. Three consequences worth stating plainly:
  • Workspace reach is its own grant, and it can be withheld. agency:read covers listing, reading and exporting client reports; agency:write starts client projects on the shared credits. Ask for neither and the key is a purely personal credential no matter whose workspace the owner belongs to. The personal scopes (analysis:*, batch:*, export:read) reach nothing in a workspace.
  • agency:read includes export. There is no separate export scope on this surface, so a key that can list client reports can also pull any completed one in full.
  • Membership is resolved live, per request. The scope is necessary, not sufficient. Removing someone from the workspace ends their Agency access on their next call even though their personal key stays valid, and suspending the account ends it immediately.
Keys created before 2026-09-09 cannot reach an Agency workspace. Until that date these routes were gated on analysis:read / analysis:write / export:read, so older keys hold only those five strings and now get 403 INSUFFICIENT_SCOPE on every /api/agent/agency/** call. Scopes are fixed at creation and are not backfilled, so recovery means a new grant, and each route has a condition. Reconnect the client and approve the Agency permissions: this 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, and an OAuth client renewing through a refresh token will not re-prompt on its own, so the reconnection has to be started by hand. Or create a new key with “Include Agency workspace access” ticked: this cannot silently fail, but manual key creation needs either a paid personal plan or membership of a Consultant or Agency workspace with an active subscription.
So on an Agency workspace, revoking a leaked agency:* key is urgent in a way it is not on a personal account: until it is revoked it can read client work and spend shared credits. Revoke from API key settings.
Steps 3 and 4 act on runs this API started. get_analysis also resolves a report the account created on the preuve.ai dashboard, but exporting or enriching one answers 403 REPORT_NOT_FROM_AGENT_RUN. Neither the refusal nor the poll is a retry: relay the refusal text, or the poll’s exportBlockedHint. One of them names the way forward for that specific report, which depends on more than the scan depth (tier, refund state and whether the payload is deliverable all decide whether an AI Context Pack is on offer), so do not derive it yourself from scanType. Running the idea again here with start_analysis and exporting that run works in every case.