> ## 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 spec is at [`/api-reference/openapi.yaml`](https://docs.preuve.ai/api-reference/openapi.yaml).

## Agent guidance rules

1. **Prefer the [MCP server](/mcp-server)** when it is connected - it handles HMAC signing for you. Fall back to the [reference client](/quickstart) for raw HTTP.
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_AGENT_SECRET` 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 reports the user ran in the web app     |
| 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; the account itself is untouched.

## 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.
```