> ## 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.

# HTTP API

> Same Preuve verdict, as JSON, from your own code.

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.

<Steps>
  <Step title="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](https://preuve.ai/app?settings=apiKeys), self-serve on a paid personal plan or in a Consultant or Agency workspace with an active subscription or a one-time unlock. That is the only path that shows you a `prv_...` value. Send it as `x-preuve-key` (see [Authentication](/authentication)).

    ```bash theme={null}
    export PREUVE_API_KEY=prv_...
    ```

    <Warning>
      Copy the key when you create it. It's shown once. Keep it out of git and out of browser code.
    </Warning>

    <Note>
      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](/).
    </Note>
  </Step>

  <Step title="Create an analysis">
    ```bash theme={null}
    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"
      }'
    ```

    <Info>
      `scanType` is required: `"starter"` is free, `"deep"` spends paid quota. `clientRunId` is how you
      retry: sending the same value again returns the existing run instead of starting a second one.
      Optional context fields sharpen the report: `stage` (`idea | validation | mvp | launched | growth   | scaling`) and `budget` (`bootstrap | 10k | 50k | 100k | 100kPlus | 1mPlus`) feed the feasibility
      analysis directly — the MCP tools make both **required** on a personal deep scan. An Agency client
      project is always deep and keeps both optional, as free text.
    </Info>

    <Accordion title="Same call in JavaScript">
      ```javascript theme={null}
      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);

      ```
    </Accordion>
  </Step>

  <Step title="Poll until complete">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="Enrich, then export">
    ```bash theme={null}
    # 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](/scans-and-enrichment).
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="MCP server" icon="plug" href="/mcp-server">
    Same verdict, from the chat you are already in.
  </Card>

  <Card title="Batches" icon="layer-group" href="/api-reference/introduction">
    Score up to 5 ideas over HTTP and rank them by viability.
  </Card>

  <Card title="Deep modules" icon="puzzle-piece" href="/modules">
    Proof of Demand, Founder Fit, Playbook, and Trends on demand.
  </Card>

  <Card title="Quotas and billing" icon="credit-card" href="/quotas-and-billing">
    What gets charged, and what gets refunded.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.