> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venture.caplia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Mint a key, send a deck, get back enriched company data - under three minutes.

By the end of this page, you'll have:

1. ✅ Minted a personal access token from your Caplia settings
2. ✅ Hit `/v1/health` to confirm auth works
3. ✅ Submitted a pitch deck via `POST /v1/decks`
4. ✅ Polled the resulting job until the company appears with its CRI score

Total time: about three minutes. You'll need a terminal with `curl`.

## Step 1 - Create an API key

In the Caplia portal, go to **Settings → API Keys → Create new key**:

1. Give it a name (e.g. "CRM integration", "Zapier test")
2. Choose scope: pick `write` if you're sending decks; `read` is enough for read-only integrations
3. Click **Create**

You'll see the plaintext key **exactly once** - it looks like:

```
cap_inv_live_8H3jK9pQrM2nXz7vL4tBwY6cF1aRdNeS
```

Copy it somewhere safe. If you lose it, you'll need to revoke and create a new one - Caplia never stores the plaintext.

<Tip>
  Set it as an environment variable in your shell so the rest of this guide is copy-paste-able:

  ```bash theme={null}
  export CAPLIA_KEY=cap_inv_live_8H3jK9pQrM2nXz7vL4tBwY6cF1aRdNeS
  ```
</Tip>

## Step 2 - Confirm the key works

The `/v1/health` endpoint doesn't require auth, but it's a useful first check:

```bash theme={null}
curl https://api.venture.caplia.ai/v1/health
```

```json Response theme={null}
{
  "status": "ok",
  "version": "v1"
}
```

Now try an authenticated request - list companies in your pipeline:

```bash theme={null}
curl https://api.venture.caplia.ai/v1/companies \
  -H "Authorization: Bearer $CAPLIA_KEY"
```

```json Response theme={null}
[
  {
    "id": "5a1c...",
    "name": "Tesla",
    "industry": "Energy",
    "stage": "Series A",
    ...
  },
  ...
]
```

If you see a `401`, double-check the `Authorization` header - it should be `Bearer cap_inv_live_...` with a single space between.

## Step 3 - Submit a pitch deck

This is the main "push deals in" flow. The deck goes through Caplia's intake pipeline, gets text-extracted, the company is created, then CRI and thesis scores compute in the background.

```bash theme={null}
curl -X POST https://api.venture.caplia.ai/v1/decks \
  -H "Authorization: Bearer $CAPLIA_KEY" \
  -F "file=@pitch.pdf" \
  -F "company_name=Tesla" \
  -F "company_url=https://tesla.com" \
  -F "notes=Met them at YC demo day - interesting battery tech angle" \
  -F "founder_name=Elon Musk" \
  -F "founder_email=elon@tesla.com" \
  -F 'properties={"Award Category":"Climate Tech"}'
```

```json Response (202 Accepted) theme={null}
{
  "job_id": "intake-event-uuid-here",
  "status": "queued",
  "poll_url": "https://api.venture.caplia.ai/v1/jobs/intake-event-uuid-here"
}
```

The response comes back fast - the actual processing happens asynchronously. All fields besides `file` are optional but help the worker create a cleaner company record:

* `founder_name` / `founder_email` become the company's **contact card**.
* `properties` tags the deal with your team's **custom properties** (a JSON object of property → option, e.g. an awards programme's category). Property names and option labels are configured per team inside Caplia — discover the current values with `GET /v1/properties`, and prefer submitting the returned **ids** so internal renames never break your integration. Unknown or archived entries are skipped (with a server-side warning) rather than failing the submission.

```bash theme={null}
curl https://api.venture.caplia.ai/v1/properties \
  -H "Authorization: Bearer $CAPLIA_KEY"
```

```json theme={null}
{
  "properties": [
    {
      "id": "a99031b5-…",
      "name": "Award Category",
      "options": [
        { "id": "5e2c…", "label": "Climate Tech" },
        { "id": "9b41…", "label": "Deep Tech" }
      ]
    }
  ]
}
```

<Note>
  The deck file must be a PDF, ≤ 50 MB. Decks submitted via the API auto-approve into your pipeline - the act of holding a scoped API key is sufficient trust.
</Note>

## Step 4 - Poll the job

The job moves through `queued → processing → completed`. Poll every 3 seconds:

```bash theme={null}
curl https://api.venture.caplia.ai/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $CAPLIA_KEY"
```

Early in the job lifecycle:

```json theme={null}
{
  "job_id": "...",
  "status": "queued",
  "company_id": null,
  "created_at": "2026-05-12T10:32:00Z",
  "completed_at": null,
  "results": null,
  "errors": []
}
```

Once the company has been created (typically 10-30 seconds in):

```json theme={null}
{
  "job_id": "...",
  "status": "processing",
  "company_id": "5a1c...",
  "results": {
    "company": {
      "id": "5a1c...",
      "name": "Tesla",
      "problem_statement": "Affordable electric vehicles for mass adoption",
      "industry": "Energy",
      "stage": "Series A",
      "website": "https://tesla.com"
    }
  },
  "errors": []
}
```

When scoring completes (typically 1-2 minutes in):

```json theme={null}
{
  "job_id": "...",
  "status": "completed",
  "completed_at": "2026-05-12T10:33:14Z",
  "results": {
    "company": { /* ... */ },
    "cri": {
      "score": 78,
      "scored_at": "2026-05-12T10:33:01Z",
      "domains": [ /* ... */ ]
    },
    "thesis_matches": [
      {
        "thesis_id": "...",
        "thesis_name": "Climate Series A",
        "score": 0.74,
        "scoring_status": "scored"
      }
    ]
  },
  "errors": []
}
```

Surface `results.company` as soon as it appears so your users see something useful; layer in `results.cri` and `results.thesis_matches` as they land.

## What's next

<CardGroup cols={2}>
  <Card title="Authentication details" icon="key" href="/authentication" horizontal>
    Key format, scopes, rotation, security best practices.
  </Card>

  <Card title="Full API reference" icon="terminal" href="/api-reference/introduction" horizontal>
    Every endpoint, every parameter, with try-it-yourself examples.
  </Card>
</CardGroup>