> ## Documentation Index > Fetch the complete documentation index at: https://docs.preuve.ai/llms.txt > Use this file to discover all available pages before exploring further. # For AI Agents > How agents should read these docs, call the API, and behave with a Preuve key. Guidance rules, retry semantics, and safety. 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 * Every docs page has a Markdown twin: append `.md` to its URL (e.g. `https://docs.preuve.ai/quickstart.md`). * The full docs index lives at [`/llms.txt`](https://docs.preuve.ai/llms.txt); the complete content in one file at [`/llms-full.txt`](https://docs.preuve.ai/llms-full.txt). * This docs site is itself an MCP server: connect `https://docs.preuve.ai/mcp` from any MCP client to search these docs. * The OpenAPI 3.1 spec is served on the API's own domain at [`https://preuve.ai/openapi.json`](https://preuve.ai/openapi.json) (YAML at [`/openapi.yaml`](https://preuve.ai/openapi.yaml), RFC 9727 catalog at [`/.well-known/api-catalog`](https://preuve.ai/.well-known/api-catalog)) and here at [`/api-reference/openapi.yaml`](https://docs.preuve.ai/api-reference/openapi.yaml). Same file, generated from one source. * [`GET https://preuve.ai/api/agent`](https://preuve.ai/api/agent) is the unauthenticated discovery document: auth header, costs, rate limits and every endpoint. Start there when you know nothing else. ## Getting in Start free: connect and run your first starter scans. * **A key costs nothing to obtain.** Connecting the [MCP server](/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 or a one-time unlock - see [Authentication](/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](/mcp-server)** when it is connected. Fall back to plain HTTP with the `x-preuve-key` header ([HTTP API](/quickstart)) - there is no client library to install. If you can load skills, install the [Agent Skill](/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](/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. | Can | Cannot | | - | - | | Create starter and deep analysis runs for the owning account | Log into preuve.ai or read the dashboard | | Poll, enrich, and export runs **it created** | See the owner's **personal** web-app reports | | Start deep modules on its own deep reports | Change plans, buy tokens, or manage billing | | Create public share links (only with explicit `publish`) | Create or revoke API keys | 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](/mcp-server#agency-client-projects), 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": | Can, and the scope that grants it | Still cannot | | - | - | | **`agency:read`** — list every client report in the workspace, including ones created in the dashboard | Read another workspace's reports | | **`agency:read`** — export any completed client report in full | Email a client or publish a client share | | **`agency:write`** — start client projects against the workspace's **shared** project credits | Manage the workspace, its team, or billing | 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 or a one-time unlock. 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](https://preuve.ai/app?settings=apiKeys). ## Recommended agent workflow ```text theme={null} 1. start_analysis { clientRunId, scanType: "starter", idea } 2. get_analysis until status = COMPLETED (poll every 10-30s) 3. export_analysis -> ideas-json (scores, verdict, competitors, risks, citations) 4. Only if the user asks for the full report: start_analysis with scanType: "deep", then enrich_analysis (+ modules), then export. ``` 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 Build with AI is available), so do not derive it yourself from `scanType`. Running the idea again here with `start_analysis` and exporting that run works in every case. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.