HTTP API

Score ideas from a script or backend: viability score, competitors, source-linked evidence. One header, no SDK. For Claude, Cursor, or Codex, use Get started instead.

Get your key

Calling the API from your own code needs a key you hold yourself, so create one by hand at Account → API Keys, self-serve on Founder and above. That is the only path that shows you a prv_... value. Send it as x-preuve-key (see Authentication).

export PREUVE_API_KEY=prv_...

Copy the key when you create it. It’s shown once. Keep it out of git and out of browser code.

Connecting the Preuve connector instead works on a free account, but it mints the key inside your MCP client and never shows you the value, so there is nothing to send as x-preuve-key. For that path, start at Get started.

Create an analysis

curl https://preuve.ai/api/agent/analyses \
  -H "x-preuve-key: $PREUVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "clientRunId": "my-run-001",
    "scanType": "starter",
    "idea": "A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.",
    "targetMarket": "Independent coffee shops",
    "targetCountry": "US"
  }'

Same call in JavaScript

const BASE_URL = process.env.PREUVE_AGENT_BASE_URL || 'https://preuve.ai';

export async function preuve(method, path, bodyObject = null) {
  const response = await fetch(new URL(path, BASE_URL), {
    method,
    headers: {
      'content-type': 'application/json',
      'x-preuve-key': process.env.PREUVE_API_KEY,
    },
    body: bodyObject ? JSON.stringify(bodyObject) : undefined,
  });
  return response.json();
}

const run = await preuve('POST', '/api/agent/analyses', {
clientRunId: 'my-run-001',
scanType: 'starter',
idea: 'A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.',
targetMarket: 'Independent coffee shops',
targetCountry: 'US',
});

console.log(run.id, run.status);

Poll until complete

curl https://preuve.ai/api/agent/analyses/RUN_ID \
  -H "x-preuve-key: $PREUVE_API_KEY"

Starter runs typically complete in 1-3 minutes, deep runs in 5-10. Poll every 10-15 seconds until status is COMPLETED.

Enrich, then export

# if readyForExport is false
curl -X POST https://preuve.ai/api/agent/analyses/RUN_ID/enrich \
  -H "x-preuve-key: $PREUVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{}'

curl "https://preuve.ai/api/agent/analyses/RUN_ID/export?format=ideas-json" \
  -H "x-preuve-key: $PREUVE_API_KEY"

You get stable JSON (schemaVersion: 2): score, verdict, competitors, risks, and citations. Deep scans also include the full report, pivots, and any modules. See Scans and enrichment.

Next steps

MCP server

Same verdict, from the chat you are already in.

Batches

Score up to 10 ideas and rank them by viability.

Deep modules

Proof of Demand, Founder Fit, Playbook, and Trends on demand.

Quotas and billing

What gets charged, and what gets refunded.

Getting Started

For agents

Concepts

Next steps

MCP server

Batches

Deep modules

Quotas and billing

​Next steps

MCP server

Batches

Deep modules

Quotas and billing

Next steps