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

# Quickstart

> Run your first analysis in five minutes.

## 1. Get your credentials

API keys are issued on request during early access ([request a key](https://preuve.ai/mcp#get-access)). You receive two values:

```bash theme={null}
export PREUVE_AGENT_KEY=prv_...
export PREUVE_AGENT_SECRET=prv_sk_...
```

<Warning>
  The secret is shown once at issuance and signs every request. Store it in a secret manager; never
  commit it.
</Warning>

## 2. Create an analysis

Every request is HMAC-signed (see [Authentication](/authentication)). The fastest path is the reference client below - it signs for you.

<CodeGroup>
  ```javascript signedFetch.mjs theme={null}
  import { randomBytes, createHash, createHmac } from 'node:crypto';

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

  function sha256Hex(value) {
    return createHash('sha256')
      .update(value || '')
      .digest('hex');
  }

  function canonicalQuery(searchParams) {
    const pairs = [...searchParams.entries()].filter(([k]) => k !== 'signature');
    pairs.sort((a, b) => a[0].localeCompare(b[0]) || a[1].localeCompare(b[1]));
    return pairs.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&');
  }

  export async function signedFetch(method, path, bodyObject = null) {
    const url = new URL(path, BASE_URL);
    const body = bodyObject ? JSON.stringify(bodyObject) : '';
    const timestamp = new Date().toISOString();
    const nonce = randomBytes(16).toString('hex');
    const canonical = [
      method.toUpperCase(),
      url.pathname,
      canonicalQuery(url.searchParams),
      sha256Hex(body),
      timestamp,
      nonce,
    ].join('\n');
    const signature = `sha256=${createHmac('sha256', process.env.PREUVE_AGENT_SECRET)
      .update(canonical)
      .digest('hex')}`;

    const response = await fetch(url, {
      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': signature,
      },
      body: body || undefined,
    });
    return response.json();
  }
  ```

  ```javascript createRun.mjs theme={null}
  import { signedFetch } from './signedFetch.mjs';

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

  console.log(run.id, run.status);
  ```
</CodeGroup>

<Info>
  `scanType` is required and explicit so an agent can never spend a paid deep scan by accident:
  `"free"` runs the basic analysis at no cost, `"deep"` runs the full paid analysis and consumes
  account quota. `clientRunId` is your idempotency key - re-POSTing the same value replays the
  existing run instead of creating a new one.
</Info>

## 3. Poll until complete

```javascript theme={null}
const status = await signedFetch('GET', `/api/agent/analyses/${run.id}`);
// { id, reportId, status: 'PROCESSING' | 'COMPLETED' | 'FAILED', readyForExport, enrichment, reportUrl, shareUrl }
```

Free runs typically complete in 1-3 minutes, deep runs in 5-10. Poll every 10-15 seconds.

## 4. Enrich, then export

```javascript theme={null}
if (status.status === 'COMPLETED' && !status.readyForExport) {
  await signedFetch('POST', `/api/agent/analyses/${run.id}/enrich`, {});
  // idempotent - skips already-completed sections; poll again afterwards
}

const result = await signedFetch('GET', `/api/agent/analyses/${run.id}/export?format=ideas-json`);
console.log(result.idea.score, result.idea.verdict);
```

The export is stable JSON (`schemaVersion: 2`): scores, verdict, market, competitors, SWOT, risks, quick take, action plans, and citations on every tier; full paid sections, pivots, and module payloads on deep runs. See [Scans and enrichment](/scans-and-enrichment).

## Next steps

<CardGroup cols={2}>
  <Card title="Use it from Claude" icon="message-bot" href="/mcp-server">
    Set up the Preuve MCP server in two commands.
  </Card>

  <Card title="Batches" icon="layer-group" href="/api-reference/introduction">
    Score up to 10 ideas per batch with one export.
  </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 each call consumes, and every safety net.
  </Card>
</CardGroup>