Analyses

Start an analysis

Create one analysis run. Async - poll with GET /api/agent/analyses/{id}. scanType is required and explicit: "starter" costs nothing, "deep" consumes paid account quota. clientRunId is your idempotency key: re-POSTing the same value replays the existing run.

post/api/agent/analyses

Request

  • Base URL: https://preuve.ai
  • URL: https://preuve.ai/api/agent/analyses
  • Auth: API key in header x-preuve-key

Request body

clientRunIdstring

Caller-chosen idempotency id. Reusing it replays the existing run.

scanType'starter' | 'deep'

"starter" costs nothing; "deep" runs the full paid analysis and consumes account quota. "free" is accepted as a legacy alias of "starter".

ideastring

The startup idea, in plain language.

targetMarketstring
targetCountrystring

ISO country code, e.g. "US" or "FR".

titlestring
stagestring

Where the founder is today. Canonical values: idea, validation, mvp, launched, growth, scaling (free text tolerated). Optional here, but the MCP tools require it for deep scans; it feeds the feasibility analysis.

budgetstring

Budget available to pursue the idea. Canonical values: bootstrap (no outside money), 10k, 50k, 100k, 100kPlus (over $100k), 1mPlus (over $1M); free text tolerated. Optional here, but the MCP tools require it for deep scans; it feeds the feasibility analysis.

languagestring
enrichmentMode'core' | 'none'

"core" also generates the export-required sections; "none" returns the raw completion only.

publishboolean

When true, creates a public share URL for the report.

Response

Run created (or replayed via clientRunId).

idstring uuid
reportIdstring uuid nullable

Null until the report row is attached, which is why a run that failed before dispatch is retryable under the same clientRunId.

clientRunIdstring nullable

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.

batchIdstring uuid nullable

The batch this run belongs to, or null for a standalone run.

scanType'starter' | 'deep'

Your request type. Reliable from creation, even while PROCESSING.

enrichmentMode'core' | 'none'
publishboolean
reportType'quick' | 'deep_dive' | 'null' nullable
analysisTier'basic' | 'advanced' | 'null' nullable

Derived from the report. Deep runs read "basic" until deep sections land.

status'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED'
progressStepstring nullable

Free-text pipeline stage while PROCESSING.

errorCodestring nullable

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.

errorMessagestring nullable
resetAtstring date-time

Present only on a batch item refused by the rolling daily cap; absent, not null, on every other run.

pollAfterSecondsinteger

Present only while polling is still useful. Pace by this rather than by a fixed interval.

pollHintstring

Present alongside pollAfterSeconds.

createdAtstring date-time
updatedAtstring date-time
readyForExportboolean

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.

exportableboolean

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'REPORT_NOT_FROM_AGENT_RUN'

Present alongside exportable, naming the refusal.

exportBlockedHintstring

Present alongside exportable. Relayable prose.

reportUrlstring uri nullable

Null until the report row exists.

shareUrlstring uri nullable

Changes

No recorded changes to this operation across all 1 revision of this API.