Authentication

The Caplia API uses Personal Access Tokens (PATs) sent as Bearer tokens in the Authorization header. Every request to an authenticated endpoint must include:

Authorization: Bearer cap_inv_<env>_<32 alphanumeric chars>

There is no other authentication method - no OAuth, no session cookies, no IP allowlists. PATs are tied to your individual user account; they inherit your permissions inside Caplia via row-level security.

Key format

cap_inv_live_8H3jK9pQrM2nXz7vL4tBwY6cF1aRdNeS
└─┬─┘ ─┬─ ─┬─  └────────────┬──────────────┘
  │    │   │                 │
  │    │   │                 └── 32-char alphanumeric (base62) - ~190 bits of entropy
  │    │   └──────────────────── env: `live` (production) or `test` (sandbox / staging)
  │    └──────────────────────── portal: `inv` (investor); `fnd` reserved for founder portal
  └───────────────────────────── vendor prefix

Live vs test

Two environment prefixes are minted depending on which Caplia portal you create the key from:

Prefix	Mint from	Accepted by	What it sees
`cap_inv_live_`	The production Caplia portal	`api.venture.caplia.ai` and `mcp.venture.caplia.ai`	Your real pipeline data
`cap_inv_test_`	The staging Caplia portal	`api-sandbox.venture.caplia.ai` and `mcp-sandbox.venture.caplia.ai`	Sandbox / test data, isolated from production

Use test keys when developing or testing an integration so that you can’t accidentally create or read against real deals. The production endpoints reject test keys with 401 and vice-versa, so leaking a key into the wrong environment fails closed. The prefix makes leaked keys instantly identifiable and greppable in logs. If you see cap_inv_live_* anywhere it shouldn’t be, treat it as a leak and revoke immediately.

Creating a key

Sign in to Caplia
Settings → API Keys → Create new key
Give it a descriptive name (you’ll see this in the list later - “CRM integration”, “Zapier prod”, etc.)
Pick scope: read or write (see below)
Click Create

The plaintext is shown exactly once, then never again. Caplia stores only a hash. Copy it to your secret manager immediately.

If you lose the plaintext, the key cannot be recovered - you must revoke and create a new one. This is deliberate; it means a Caplia DB leak doesn’t leak your API keys.

Scopes

v1 has two scopes. A key carries one or both.

scope

Read access to all GET endpoints - companies, scores, metrics, documents, theses, views, jobs.

scope

Read access (everything read allows) plus POST endpoints - create companies, upload decks, attach documents, add notes.

Pick read for dashboard-style integrations that only consume Caplia data. Pick write when you also need to push deals or documents in. Finer-grained scopes (companies:write, decks:write) will come in a future version when there’s real demand for delegated permissions.

Using the token

Every authenticated request needs the header:

curl https://api.venture.caplia.ai/v1/companies \
  -H "Authorization: Bearer cap_inv_live_8H3jK9pQrM2nXz7vL4tBwY6cF1aRdNeS"

Or in your language of choice:

const response = await fetch('https://api.venture.caplia.ai/v1/companies', {
  headers: {
    'Authorization': `Bearer ${process.env.CAPLIA_KEY}`,
  },
});
const companies = await response.json();

import os, requests

response = requests.get(
    'https://api.venture.caplia.ai/v1/companies',
    headers={'Authorization': f'Bearer {os.environ["CAPLIA_KEY"]}'},
)
companies = response.json()

req, _ := http.NewRequest("GET", "https://api.venture.caplia.ai/v1/companies", nil)
req.Header.Set("Authorization", "Bearer " + os.Getenv("CAPLIA_KEY"))
resp, _ := http.DefaultClient.Do(req)

require 'net/http'

uri = URI('https://api.venture.caplia.ai/v1/companies')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{ENV['CAPLIA_KEY']}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }

Error responses

If the header is missing or malformed:

401 Unauthorized

{
  "error": {
    "code": "unauthenticated",
    "message": "Missing or malformed Authorization header",
    "request_id": "req_8H3jK9pQ"
  }
}

If the key is valid but doesn’t carry the scope this endpoint requires:

403 Forbidden

{
  "error": {
    "code": "forbidden_scope",
    "message": "This endpoint requires the `write` scope",
    "request_id": "req_..."
  }
}

The request_id value is useful when emailing support - it lets us trace your exact request in our logs.

Short-lived upload tokens (`cap_upload_*`)

The Venture Form Widget — used to embed pitch-deck upload into public application forms — does not use Personal Access Tokens. Long-lived cap_inv_* keys must never ship to a browser. Instead, public form uploads use a two-step token flow that mirrors S3 presigned POSTs:

The widget calls POST /v1/uploads/sign with an opaque, server-allowlisted form_id. No auth header required.
Caplia returns a cap_upload_<jwt> token — HMAC-signed, 5-minute TTL, single-use, bound to one upload with a max size and MIME type.
The widget POSTs the PDF to POST /v1/uploads/decks with Authorization: Bearer cap_upload_<jwt>.

You never mint or manage cap_upload_* tokens by hand — Caplia issues them on behalf of allowlisted forms. They’re not interchangeable with cap_inv_* keys and they can’t read any data; they exist purely to authorise a single deck submission. See Venture Form Widget for the full integration guide.

Revoking a key

In Settings → API Keys, click the Revoke button on the row. Revocation is immediate - the next request with that key returns 401 within seconds. If you suspect a key has leaked:

Revoke first - don’t wait
Then investigate where it leaked (commit history, logs, screenshots)
Mint a new key, rotate any integrations that use the old one

Security best practices

Never commit keys to source control. Use environment variables or a secret manager.
Use one key per integration. If your CRM and your internal dashboard both call the API, give them separate keys. If one leaks you can revoke without breaking the other.
Use the least-privilege scope. Use read if the integration only reads. Reserve write for systems that actually push data in.
Rotate periodically. Caplia doesn’t enforce expiration today, but rotating every 90 days is good hygiene.
Watch the last_used_at timestamp in Settings → API Keys. A key that should be active but isn’t has either been replaced or your integration is broken.

What lives in logs

We log:

The first 12 characters of the key (cap_inv_live) plus the last 4 characters
The endpoint, status code, and request_id
The user the key belongs to

We never log:

The full plaintext key
The Authorization header
Request bodies (including uploaded files)

If you see a full key in a log line anywhere - Caplia’s, your CRM’s, your own - treat it as a leak.

Start here

Getting started

Integrations

API reference

Endpoints

Key format

Live vs test

Creating a key

Scopes

Using the token

Error responses

Short-lived upload tokens (`cap_upload_*`)

Revoking a key

Security best practices

What lives in logs

​Key format

​Live vs test

​Creating a key

​Scopes

​Using the token

​Error responses

​Short-lived upload tokens (cap_upload_*)

​Revoking a key

​Security best practices

​What lives in logs

Key format

Live vs test

Creating a key

Scopes

Using the token

Error responses

Short-lived upload tokens (`cap_upload_*`)

Revoking a key

Security best practices

What lives in logs