For AI Agents

​

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; the complete content in one file at /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.

​

Agent guidance rules

1. Prefer the MCP server when it is connected - it handles HMAC signing for you. Fall back to the reference client 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.
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

​

Recommended agent workflow

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.