> ## 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. # Export an analysis (ideas-json) > Structured JSON export (schemaVersion 2) for one COMPLETED, export-ready analysis THIS API started. Deep runs include full sections, pivots, citations, and generated module payloads. A report created on the preuve.ai dashboard is not exportable here and answers 403 REPORT_NOT_FROM_AGENT_RUN: the poll resolves it, but the data is served elsewhere. Which way forward depends on the report - Build with AI on its report page where it is available, unlocking or re-running it otherwise - and the refusal text names the right one, so relay that rather than deriving it from the scan depth. Starting a fresh analysis here always works. ## OpenAPI ````yaml /api-reference/openapi.yaml get /api/agent/analyses/{id}/export openapi: 3.1.0 info: title: Preuve Agent API version: '2.0' summary: Startup idea validation for AI agents and scripts. description: > API for programmatic startup idea validation: a 0-100 viability score, competitors, market sizing and source-linked evidence from 60+ live sources. Every request carries a single x-preuve-key header holding the whole API key - no signing, no bearer token. See the Authentication guide. Every response is JSON, errors included: an unknown route answers 404 with the same { error, code } envelope as every other failure, so branch on code and never parse a message. Error codes are stable and retired ones stay listed on the Errors page. scanType "starter" costs nothing and returns a real report, which makes it the sandbox: an agent can exercise the whole create - poll - enrich - export loop without spending a cent. GET /api/agent is the unauthenticated discovery document. termsOfService: https://preuve.ai/terms contact: name: Preuve AI developer support url: https://preuve.ai/support email: hello@preuve.ai servers: - url: https://preuve.ai security: - preuveKey: [] tags: - name: Discovery description: Unauthenticated documents that describe the API itself. - name: Analyses description: One idea at a time - create, poll, enrich, export. - name: Batches description: Up to five analyses in one idempotent batch. - name: Tools description: Utilities that spend no scan quota. - name: Agency description: >- Client work on a Consultant or Agency workspace (agency:read / agency:write). externalDocs: description: Developer docs - quickstart, authentication, quotas, error codes url: https://docs.preuve.ai/ paths: /api/agent/analyses/{id}/export: get: tags: - Analyses summary: Export an analysis (ideas-json) description: > Structured JSON export (schemaVersion 2) for one COMPLETED, export-ready analysis THIS API started. Deep runs include full sections, pivots, citations, and generated module payloads. A report created on the preuve.ai dashboard is not exportable here and answers 403 REPORT_NOT_FROM_AGENT_RUN: the poll resolves it, but the data is served elsewhere. Which way forward depends on the report - Build with AI on its report page where it is available, unlocking or re-running it otherwise - and the refusal text names the right one, so relay that rather than deriving it from the scan depth. Starting a fresh analysis here always works. operationId: exportAnalysis parameters: - $ref: '#/components/parameters/AnalysisId' - name: format in: query required: false schema: type: string enum: - ideas-json default: ideas-json - name: verbosity in: query required: false description: > Response size. "full" is the whole payload. "summary" keeps every scored field: score, verdict (including the Bottom Line narrative under details.verdict.narrative), competitors, market size, risks and pivots, plus the closing verdict under details.sections.synthesis. It drops the other section prose (keeping their numbers and short values) and counts Trends data points. On the largest reports it then reduces raw evidence and how-to material to numbers and short text and shortens other long text, never a score, rating or verdict, until the response fits 65,000 JSON characters. What it changed is listed under idea.details.omitted. This operation defaults to "full"; the batch export takes the same parameter but is meant to be called with "summary". schema: type: string enum: - full - summary default: full responses: '200': description: The export payload. content: application/json: schema: $ref: '#/components/schemas/AnalysisExport' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': description: > The key lacks export:read (INSUFFICIENT_SCOPE), or the report was created on the preuve.ai dashboard (REPORT_NOT_FROM_AGENT_RUN). content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': $ref: '#/components/responses/NotFound' '409': description: >- Not exportable yet (ANALYSIS_NOT_COMPLETE or ENRICHMENT_NOT_COMPLETE). content: application/json: schema: $ref: '#/components/schemas/ApiError' '422': description: The analysis failed (ANALYSIS_FAILED). content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: AnalysisId: name: id in: path required: true description: > Run id (returned by create) or report id. What resolves differs per route: the poll also accepts any personal starter or deep report the account owns, including dashboard-created ones (the UUID in /app/results?id=...), while export and enrich serve analyses this API started. See each operation. schema: type: string format: uuid schemas: AnalysisExport: type: object description: > ideas-json export, schemaVersion 2. Deep-only fields are null on free runs. See the Scans and Enrichment guide for the field-by-field contract. properties: schemaVersion: type: integer const: 2 exportType: type: string enum: - analysis exportedAt: type: string format: date-time analysis: $ref: '#/components/schemas/AnalysisRun' verbosity: type: string enum: - full - summary description: > The verbosity this payload was built at, echoed back. On "summary", idea.details.omitted names what was dropped. locked: $ref: '#/components/schemas/ExportLocks' upsell: $ref: '#/components/schemas/ExportUpsell' idea: type: object properties: rank: type: integer verdict: type: string score: type: number title: type: string risk: type: string quote: type: string evidence: type: string domains: type: array items: type: string reportId: type: string reportUrl: type: string shareUrl: type: - string - 'null' details: type: object description: > Summary contract on every tier (including situationBriefing and scores); sections/pivots/communityDemand/founderFit/playbook/proofOfDemand/googleTrends on deep runs. `details.cloneability` is present on every tier but changes shape rather than going null - three fields on starter runs, the full analysis on deep runs. See the Scans and Enrichment guide. ApiError: type: object required: - error - code description: > Every error, on every route, unknown paths included. Some codes add top-level context fields (limit, tokenBalance, resetAt, upsell, ...); a 404 NOT_FOUND on an unknown route adds details.discovery, details.openapi and details.docs so the caller can recover. properties: error: type: string description: Human-readable message. Prose; it changes. code: type: string description: Stable machine-readable code. Branch on this. details: description: > Optional context. An object on most codes (limits, recovery links, the method and path of a 404); an array of strings where the route forwards a validator's messages, as enrich does on INVALID_FOUNDER_PROFILE. Read it, never branch on it - `code` is the contract. oneOf: - type: object additionalProperties: true - type: array items: type: string limit: type: integer description: > The ceiling that was hit, in the unit the code implies: bytes on PAYLOAD_TOO_LARGE, runs in flight on CONCURRENT_LIMIT_REACHED, requests in the window on a rate limit. remaining: type: integer description: Requests left in the current window. resetAt: type: string format: date-time description: > When the window that refused this request reopens. Present on DAILY_LIMIT_REACHED from run creation (the idea generator's rolling ceiling sends only limit); prefer it over the Retry-After header when both are present, since it is absolute. tokenBalance: type: integer description: >- Deep-scan credits left on the account. Present on INSUFFICIENT_TOKENS. scansUsed: type: integer scansRemaining: type: integer limitType: type: string description: Which ceiling refused an AppSumo-backed account. upgradeHint: type: string description: What to change to get past this refusal. Prose, not a contract. paused: type: boolean description: > Present only on the LLM-pause 503, where the body is exactly { error, code, paused }. upsell: $ref: '#/components/schemas/ExportUpsell' AnalysisRun: type: object properties: id: type: string format: uuid reportId: type: - string - 'null' format: uuid description: > Null until the report row is attached, which is why a run that failed before dispatch is retryable under the same clientRunId. clientRunId: type: - string - 'null' description: > The caller-chosen id from create. Null when the analysis is a dashboard-created report resolved by its report id: no run row exists, so there is no clientRunId to replay. batchId: type: - string - 'null' format: uuid description: The batch this run belongs to, or null for a standalone run. scanType: type: string enum: - starter - deep description: Your request type. Reliable from creation, even while PROCESSING. enrichmentMode: type: string enum: - core - none publish: type: boolean reportType: type: - string - 'null' enum: - quick - deep_dive - null analysisTier: type: - string - 'null' enum: - basic - advanced - null description: >- Derived from the report. Deep runs read "basic" until deep sections land. status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED progressStep: type: - string - 'null' description: Free-text pipeline stage while PROCESSING. errorCode: type: - string - 'null' description: > Set on a FAILED run. Two internal markers are deliberately rewritten before they leave: an ambiguous dispatch reports TRIGGER_DISPATCH_FAILED and an ambiguous claim refund reports REPORT_CREATE_FAILED. errorMessage: type: - string - 'null' resetAt: type: string format: date-time description: > Present only on a batch item refused by the rolling daily cap; absent, not null, on every other run. pollAfterSeconds: type: integer description: > Present only while polling is still useful. Pace by this rather than by a fixed interval. pollHint: type: string description: Present alongside pollAfterSeconds. createdAt: type: string format: date-time updatedAt: type: string format: date-time readyForExport: type: boolean description: > Whether GET /export will serve this analysis now. Always false for a report created on the preuve.ai dashboard, whatever state the report is in, because that export answers 403 REPORT_NOT_FROM_AGENT_RUN. Branch on exportable first. exportable: type: boolean description: > Present, and false, only on a report created on the preuve.ai dashboard. Absent means the ordinary contract applies and readyForExport is the gate. When it is false, no amount of polling or enriching changes it. exportBlockedCode: type: string enum: - REPORT_NOT_FROM_AGENT_RUN description: Present alongside exportable, naming the refusal. exportBlockedHint: type: string description: Present alongside exportable. Relayable prose. enrichment: $ref: '#/components/schemas/EnrichmentState' modules: type: - object - 'null' description: Per-module statuses. Deep reports only; null on free runs. properties: proofOfDemand: $ref: '#/components/schemas/ModuleStatus' founderFit: $ref: '#/components/schemas/ModuleStatus' playbook: $ref: '#/components/schemas/ModuleStatus' trends: $ref: '#/components/schemas/ModuleStatus' community: $ref: '#/components/schemas/ModuleStatus' reportUrl: type: - string - 'null' format: uri description: Null until the report row exists. shareUrl: type: - string - 'null' format: uri ExportLocks: type: object description: > Which fields this export left null, and why. Present only when the caller's tier withheld something, and absent entirely when the payload is complete. Read it before concluding a field is absent: a null under one of these paths is locked, not missing and not a failed analysis. It ships to every tier, paid included, and carries no price and no URL. On a batch export there is ONE object for the whole batch, the union of every exported item's withheld fields, deduplicated by path. properties: reason: type: string description: Why the fields were withheld. "starter_scan" today. unlockedBy: type: string description: What lifts the lock. "founder_report" today. fields: type: array description: One entry per withheld field. items: type: object properties: path: type: string description: > Dotted path into the export, e.g. "details.pivots". A path may name several keys of one object with a pipe, e.g. "details.risks[].explanation|mitigation". label: type: string description: > What that path holds, in plain language. Some labels also say the field needs an enrich call once the report is deep. note: type: string description: > One sentence restating that the nulls are a tier boundary rather than missing data. ExportUpsell: type: object description: > Purchase context for a locked export or buyable quota refusal. Export upsells are free-owner only; a paid non-regional caller may receive a scan_pack top-up on INSUFFICIENT_TOKENS. Ignore it if you only need the data contract. properties: offer: type: string enum: - founder_report - scan_pack description: > "founder_report" is the $59 one-time tier. "scan_pack" is a top-up for an account that already bought and has no deep credits left. price: type: string description: Display price text, e.g. "$59 one-time". guarantee: type: string description: > Guarantee text for offer=founder_report. Omitted for scan_pack top-ups; an empty string is never used. url: type: string format: uri description: Purchase or report URL, with attribution query parameters. locked: type: array description: > Section names the offer covers. Distinct from the top-level locked object, which names response FIELDS. items: type: string note: type: string description: The same facts as one sentence, for a client that relays text. EnrichmentState: type: object description: > Progress of the core export sections. The four name arrays partition `required`, so a poller decides what to do next by reading them rather than by parsing `status`: anything in processing means keep polling, anything in failed means call enrich again, and missing with nothing processing means enrichment was never started for it. properties: mode: type: string enum: - core - none status: type: string enum: - not_required - pending - processing - partial - completed - failed description: > Rolled up from the arrays below. "partial" means some sections landed and others did not; "not_required" is mode "none", or a report with no required sections. required: type: array description: >- Every section this report and mode need. The other four arrays partition it. items: type: string completed: type: array items: type: string missing: type: array description: Required, not generated, and not currently being generated. items: type: string processing: type: array description: >- Generation is in flight. Keep polling rather than calling enrich again. items: type: string failed: type: array description: >- Generation was attempted and failed. Retryable by calling enrich again. items: type: string sections: type: object description: > Per-section detail, keyed by section name, for every entry in required. Each value carries at least a status matching the array the section is in, plus completedAt on a completed section and whatever the last attempt recorded on a failed one. additionalProperties: type: object properties: status: type: string enum: - missing - processing - completed - failed - pending completedAt: type: - string - 'null' format: date-time additionalProperties: true ModuleStatus: type: object properties: status: type: string enum: - not_generated - generating - failed - completed responses: BadRequest: description: > The request was rejected before any work started: malformed JSON (INVALID_JSON), an id that is not one of ours (INVALID_ANALYSIS_ID, INVALID_BATCH_ID), an export format we do not serve (UNSUPPORTED_FORMAT), or a field the schema cannot express - an idea too short to analyse, a batch outside 1..5 items (INVALID_BATCH_SIZE), two batch items sharing a clientRunId (DUPLICATE_CLIENT_RUN_ID), an unknown scanType. No paid quota, tokens, or scans were consumed. On the CREATE routes a rate-limit window can still be: those per-account limiters are claimed ahead of schema validation on purpose, so that malformed spam is metered, and retrying unchanged spends another slot. Enrich no longer works that way - since 2026-09-15 its 12/min window is claimed after the body is validated, so a malformed enrich costs nothing. Fix the request either way; retrying it unchanged returns the same answer. content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: > Missing x-preuve-key header (MISSING_API_KEY), or a malformed, unknown or revoked key (INVALID_AGENT_KEY - the same envelope for all three, on purpose). Repeated failures are throttled per IP and answer 429. content: application/json: schema: $ref: '#/components/schemas/ApiError' NotFound: description: > Unknown id, or the resource belongs to another account. The code names what was looked up: ANALYSIS_NOT_FOUND on the analysis routes, BATCH_NOT_FOUND on the batch ones. The analysis routes also answer REPORT_DELETED when the run exists but its report was deleted from the dashboard: nothing is left to poll, enrich or export. content: application/json: schema: $ref: '#/components/schemas/ApiError' InternalError: description: > Unexpected server error (INTERNAL_ERROR, or TRIGGER_DISPATCH_FAILED when a deep scan could not be handed to the job runner). Never tell the user their quota is safe: on a deep scan the spend can already have happened when the failure hit, and an ambiguous dispatch deliberately keeps the report and its funding because the job may have been accepted before its response was lost. Treat consumption as unknown and retry with backoff. On an operation that takes a clientRunId, retry with the SAME one - that reconciles the original run, whatever state it reached, instead of starting and charging for a second one. On every other operation there is nothing to reconcile: the read or export simply failed, so a plain backed-off retry is the whole recovery. content: application/json: schema: $ref: '#/components/schemas/ApiError' ServiceUnavailable: description: > A dependency was unavailable or deliberately paused (SERVICE_DISABLED, LLM_PAUSED, PROFILE_LOOKUP_FAILED, and the fail-closed answer when the rate-limit backend is down). Any authenticated route can answer this one: authentication meters itself through the same fail-closed limiter, so an outage there refuses the request before the handler runs. Retryable, and no paid quota, tokens, or scans were consumed - a pause that lands mid-run refunds the claim it had already made. Back off and try again rather than falling back to a different endpoint. content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: preuveKey: type: apiKey in: header name: x-preuve-key description: > Your API key (prv_...), sent as-is. It is the only credential the API needs - see the Authentication guide. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.