The Preuve AI startup validation API lets any AI agent validate startup ideas programmatically. The signed (HMAC) Agent API and its MCP server are live in early access (beta) and work with Claude Code, Cursor, Codex, and custom scripts. The API runs the Preuve analysis and returns a viability score, market research, competitor analysis, a structured ideas-json export, and a shareable report URL. Deep reports can generate optional modules: Proof of Demand, Founder Fit, Playbook, and Trends. A ready-made Agent Skill at docs.preuve.ai/agent-skill teaches AI agents the full Preuve workflow, including quota safety and retry semantics. API keys never grant access to the Preuve dashboard or account settings.
MCP · Agent API · Early access
Validate the idea before your agent builds it.
Your agent ships in minutes, but only 18.3% of ideas earn a go. Preuve runs a full, source-linked viability check inside Claude Code, Cursor, or Codex - over the signed API or the MCP server.
You: validate "AI standup bot for remote teams" agent → preuve.start_analysis(idea, scanType: "starter") agent → preuve.get_analysis(run) # polls until COMPLETED ✓ Viability 38/100 - weak demand, crowded category ✗ 3 blocking risks - 12 active competitors → Don't build it yet. 2 stronger pivots attached.
- 6,000+
- ideas analyzed
- 18.3%
- earn a go-verdict
- 50+
- live sources per scan
- ~8 min
- to a scored verdict
Get your API key
Seven MCP tools wrap the signed Agent API - your agent validates ideas mid-build, no signing code. Pair it with the Agent Skill so your agent knows the full workflow from the first call. Beta: rough edges possible, failed runs always refund. Paid accounts generate their key instantly:
API keys are tied to a paid Preuve account. Create yours, then generate the key here.
Create your accountAlready have one? Sign in and come back - this form will recognize you.
# Early access beta - the server ships with your API key
claude mcp add preuve \
--env PREUVE_AGENT_KEY=prv_... \
--env PREUVE_AGENT_SECRET=prv_sk_... \
-- node preuve-mcp-server.mjs
# 7 tools: start_analysis, get_analysis, enrich_analysis,
# export_analysis, create_batch, get_batch, export_batchStartup validation API
Available now. This signed AI agent API creates analysis runs (no-cost Starter scans or full paid deep scans), polls them, generates the export sections and optional deep modules, and returns the same analysis a human user gets - as structured JSON.
Endpoints
Keys are self-serve for paid accounts and carry explicit scopes. Analysis usage is charged to the owning account quota - Starter scans at no cost, deep scans from subscription, lifetime, or token balance.
/api/agent/analysesanalysis:writeStart one analysis (starter or deep)/api/agent/analyses/:idanalysis:readPoll one analysis/api/agent/analyses/:id/enrichanalysis:writeGenerate export sections + deep modules/api/agent/analyses/:id/exportexport:readExport one analysis as JSON/api/agent/analysis-batchesbatch:writeStart up to 10 analyses/api/agent/analysis-batches/:idbatch:readPoll a batch/api/agent/analysis-batches/:id/exportexport:readExport a batch as JSONSigning
Send x-preuve-key, x-preuve-timestamp, x-preuve-nonce, and x-preuve-signature. Nonces are single-use inside a five minute window.
body='{"clientRunId":"run-online-001","scanType":"starter","idea":"A workflow automation service for solo founders that validates market demand before they build.","publish":true}'
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
nonce=$(openssl rand -hex 16)
body_hash=$(printf "%s" "$body" | openssl dgst -sha256 -binary | xxd -p -c 256)
canonical="POST
/api/agent/analyses
$body_hash
$timestamp
$nonce"
signature="sha256=$(printf "%s" "$canonical" | openssl dgst -sha256 -hmac "$PREUVE_AGENT_SECRET" -binary | xxd -p -c 256)"
curl https://preuve.ai/api/agent/analyses \
-H "content-type: application/json" \
-H "x-preuve-key: $PREUVE_AGENT_KEY" \
-H "x-preuve-timestamp: $timestamp" \
-H "x-preuve-nonce: $nonce" \
-H "x-preuve-signature: $signature" \
--data "$body"Node client
Keep PREUVE_AGENT_SECRET server-side. The canonical query line is empty when the request has no query parameters.
import { createHash, createHmac, randomUUID } from 'node:crypto';
async function signedFetch(path, { method = 'GET', body } = {}) {
const rawBody = body ? JSON.stringify(body) : '';
const timestamp = new Date().toISOString();
const nonce = randomUUID();
const canonical = [
method,
path,
'',
createHash('sha256').update(rawBody).digest('hex'),
timestamp,
nonce,
].join('\n');
const signature = createHmac('sha256', process.env.PREUVE_AGENT_SECRET)
.update(canonical)
.digest('hex');
return fetch(`https://preuve.ai${path}`, {
method,
headers: {
'content-type': 'application/json',
'x-preuve-key': process.env.PREUVE_AGENT_KEY,
'x-preuve-timestamp': timestamp,
'x-preuve-nonce': nonce,
'x-preuve-signature': `sha256=${signature}`,
},
body: rawBody || undefined,
});
}Scopes
Scopes are exact. Write access for analyses does not grant export access.
analysis:writeCreate analysis runs and enrich them for the key owneranalysis:readPoll single-run status, module states, and URLsbatch:writeCreate bounded batches up to 10 ideasbatch:readPoll batch status and child run URLsexport:readExport completed analyses and batches as JSONResponses
Polling returns status, enrichment progress, per-module states, and URLs. The export endpoint returns the structured report itself (ideas-json, schemaVersion 2) - full deep sections included on paid runs.
{
"id": "run_123",
"reportId": "report_123",
"clientRunId": "run-online-001",
"scanType": "deep",
"analysisTier": "advanced",
"status": "COMPLETED",
"readyForExport": true,
"enrichment": { "mode": "core", "status": "completed" },
"modules": {
"proofOfDemand": { "status": "completed" },
"founderFit": { "status": "not_generated" },
"playbook": { "status": "generating" },
"trends": { "status": "not_generated" }
},
"reportUrl": "https://preuve.ai/app/results?id=report_123",
"shareUrl": "https://preuve.ai/share/abc123"
}Deep modules
Paid deep reports can generate four optional modules through the enrich endpoint. One successful generation per module per report, included in the deep scan price - a failed generation never consumes the cap.
proofOfDemandVerified real-demand prospects with verbatim quotes. Beta: results can be uneven, every quote links to its source.asyncfounderFitFounder-vs-plan underwriting from a submitted founder profile: fit score, top risks, pivot fit.inlineplaybookA concrete launch playbook generated for the validated idea.asynctrendsGoogle Trends data for the idea, generated on demand - the analysis never fetches it on its own.asyncStatus lifecycle
Batches aggregate child runs into PROCESSING, COMPLETED, PARTIAL, or FAILED.
PENDINGThe run record exists and is waiting for dispatchPROCESSINGThe Preuve analysis pipeline is runningCOMPLETEDThe report is done - enrich if needed, then exportFAILEDThe run reached a terminal error with a stable codereportUrl
/app/results?id=<reportId>Private owner dashboard
shareUrl
/share/<shareId>Public shared dashboard
ideas-json
schemaVersion: 2Structured export for single runs and batches
What a key can do - and what it can't
An API key is a scoped analysis credential, not a login. It shares your account quota, and nothing else about your account.
Included
- Run analyses. No-cost Starter scans (Reality Checks) and full paid deep scans, drawn from your account quota.
- Poll and enrich. Run status, per-module states, idempotent enrichment of export sections.
- Structured exports. Stable ideas-json (schemaVersion 2): scores, research, and the full deep report body on paid runs.
- Deep modules. Proof of Demand, Founder Fit, Playbook, and Trends on your deep reports.
- Share URLs. Optional public share links when you pass publish: true.
Not included
- No dashboard access. A key cannot log into preuve.ai, read your account, or open the dashboard. It is not a session.
- No account or billing control. Keys cannot change plans, buy tokens, manage payment methods, or create/revoke other keys.
- API-created runs only. A key only sees analyses it created. Reports you ran in the web app stay invisible to it.
- No profile writes. A founder profile submitted for Founder Fit is scoped to that report - it never rewrites your account preferences.
Startup validation API FAQ
What is the Preuve startup validation API?
It is a signed HTTP API that runs a Preuve analysis on a startup idea and returns a viability score, market research, competitor analysis, a shareable report URL, and a structured JSON export. You authenticate each request with an HMAC signature, so any AI agent, CLI, or backend script can validate ideas programmatically.
Is there a Preuve MCP server?
Yes - the MCP server is live in early access (beta). It wraps the Agent API 1:1 over stdio with seven tools (start_analysis, get_analysis, enrich_analysis, export_analysis, create_batch, get_batch, export_batch) and ships with your API key. Any MCP client works: Claude Code, Cursor, Codex, or your own. A ready-made Agent Skill (docs.preuve.ai/agent-skill) teaches your agent the full workflow: scan-type quota safety, polling, enrichment gates, and safe retries. Beta means occasional rough edges - failed runs refund what they claimed, and error codes are stable so agents can retry safely. A one-line npx CLI package is planned next.
How do I get a startup validation API key?
API keys are self-serve for paid Preuve accounts - generate yours instantly from the account panel (start on this page). Each key is scoped (analysis:write, analysis:read, batch:write, batch:read, export:read), HMAC-signed on every request, and tied to one Preuve account.
What is the difference between a starter and a deep scan?
scanType is explicit on every run. "starter" runs the Reality Check at no cost from your Starter scan allowance. "deep" runs the full paid analysis (15+ sections, pivots, citations) and consumes your account quota: subscription scans first, then lifetime monthly scans, then tokens. An agent can never spend paid quota by accident, and a refused deep scan fails loudly instead of silently downgrading.
What does the API return?
Polling returns run status, enrichment progress, per-module states, and URLs. The export endpoint returns structured ideas-json (schemaVersion 2): scores, verdict, market, competitors, SWOT, risks, quick take, and citations on every tier, plus the full deep report body (sections, pivots, and generated module payloads) on paid deep runs owned by your key.
What are deep modules?
Optional add-on generations on paid deep reports, requested through the enrich endpoint: proofOfDemand (verified real-demand prospects), founderFit (founder-vs-plan underwriting from your founder profile), playbook (launch playbook), and trends (on-demand Google Trends). Each module is capped at one successful generation per report and is included in the deep report price - no extra fee.
Does an API key give access to my Preuve dashboard or account?
No. A key is not a login: it cannot open the dashboard, read your account, change billing, or manage other keys. It only sees analyses it created through the API - reports you ran in the web app stay invisible to it. If a key leaks, revoke it; your account itself is untouched.
How much does the validation API cost?
API usage draws from the same analysis quota as your Preuve plan - Starter scans from your Starter allowance at no cost, deep scans from your subscription, lifetime, or token balance. There is no separate API fee, and failed runs refund whatever they claimed.
Should I validate before using an autonomous agent like Polsia?
Yes. Autonomous build agents such as Polsia execute fast but skip the demand-validation step, which is where most teams burn their runway. Run the idea through the Preuve validation API first, then hand a validated brief to your build agent. See the linked Polsia review for a deeper breakdown of that gap.
New to Preuve? See how the analysis works on the idea validation page, browse real example reports, or check pricing and scan limits. Weighing an autonomous build agent? Read our honest Polsia review on why validation has to come first.