> ## 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.
# API Reference
> Every Caplia API endpoint, with try-it-yourself examples.
This section contains the full reference for every endpoint in v1 of the Caplia API. Each endpoint page has:
* Path, method, required scope
* Path / query / body parameters with types
* Example requests in curl, Node, Python, Go, Ruby
* Example success and error responses
* A live "Try it" playground (paste your key, hit run)
## Conventions
### Base URL
```
https://api.venture.caplia.ai
```
All paths shown in this reference are appended to that base.
### Authentication
Every endpoint except `GET /v1/health` and `GET /v1/openapi.json` requires the `Authorization: Bearer cap_inv_live_...` header. See [Authentication](/authentication) for key format, scopes, and rotation.
### Response shape
**Success** - bare resource (no envelope):
```json theme={null}
{
"id": "5a1c...",
"name": "Tesla",
...
}
```
**Error** - always envelope-wrapped:
```json theme={null}
{
"error": {
"code": "company_not_found",
"message": "No company with id abc-123 in your pipeline",
"request_id": "req_8H3jK9pQ"
}
}
```
Always include `request_id` when contacting support.
### Status codes
| Code | Meaning |
| ----- | --------------------------------------------------------- |
| `200` | Read success |
| `201` | Create success |
| `202` | Accepted but async - see `/v1/jobs/{id}` to track |
| `400` | Bad input (validation) |
| `401` | Missing or invalid API key |
| `403` | Key valid, but doesn't carry the required scope |
| `404` | Resource not found, or outside your team's visibility |
| `409` | Conflict (e.g. duplicate submission) |
| `429` | Rate limited (not yet enforced in v1) |
| `500` | Unexpected server error - please report with `request_id` |
We deliberately return `404` rather than `403` when you query a resource you can see structurally but don't own - this prevents enumeration of other teams' data.
### Pagination
Endpoints that return lists support cursor-based pagination:
```bash theme={null}
curl "https://api.venture.caplia.ai/v1/companies?limit=50&cursor=Y3Vyc29yX2RhdGE="
```
When more results are available, the response includes a `next_cursor`:
```json theme={null}
{
"data": [ /* ... */ ],
"next_cursor": "Y3Vyc29yX2RhdGE="
}
```
Pass that value back as `cursor` to fetch the next page. Default `limit` is 25, max is 100.
### OpenAPI spec
The machine-readable spec lives at:
```
https://api.venture.caplia.ai/v1/openapi.json
```
You can pipe this into Postman, Insomnia, or any OpenAPI-aware tool. It's regenerated automatically from the live API on every deploy, so it's always in sync with what the server actually does.
## Endpoints by category
List, get, create, search companies in your pipeline.
CRI scores, thesis matches, traction metrics, key metrics.
List folders, documents; get signed download URLs; upload new documents.
Submit pitch decks; target one or more pipelines; poll job status; receive enriched results.
Discover the pipelines your key can submit into, including the default landing pipeline.
Your team's investment theses and pipeline view configurations.
Liveness check and machine-readable OpenAPI spec.
Use the sidebar to jump to a specific endpoint.
## Submitting into a specific pipeline
Teams can run several pipelines at once — for example one per award in an awards programme, where an entrant may enter two or three awards. Submissions target pipelines with the `pipeline_ids` field:
1. **Discover** the pipelines your key can submit into with `GET /v1/pipelines`. The response lists each pipeline's `id`, `name`, and whether it is the default landing pipeline (where submissions go when you omit `pipeline_ids`).
2. **Submit** with `pipeline_ids` on `POST /v1/decks` (as a JSON array or comma-separated multipart field) or `POST /v1/companies` (as a JSON array). One deal is created per pipeline, so a company entering two awards appears on both.
3. Ids outside your key's scope are rejected with a `400` before anything is created.
Custom application questions work the same way: discover them with `GET /v1/properties` and answer them via the `properties` field on either endpoint.
## Store your own reference, query it back
Store your system's reference (an application ID, a CRM id) as a **reference property** on submission, and you can always find the company again — even if you never captured the `company_id` from the intake job. Reference properties are made for identifiers: they never display as application answers, and they can carry a `validation_pattern` (a full-match regex returned by `GET /v1/properties`) — validate your value against it before sending, because non-matching values are not stored:
```bash theme={null}
curl "https://api.venture.caplia.ai/v1/companies?property=Application%20ID&value=APP-123" \
-H "Authorization: Bearer $CAPLIA_API_KEY"
```
`GET /v1/companies/{id}` echoes every submitted property back, so both sides of the reconciliation are covered. Reference and text values match exactly (case-sensitive); select values accept an option label or id.
## Worked example: submit an application
A full application — deck, applicant contact, award targeting, and question answers — is one discovery pass and one `POST`.
```bash theme={null}
curl https://api.venture.caplia.ai/v1/properties \
-H "Authorization: Bearer $CAPLIA_API_KEY"
```
```json theme={null}
{
"properties": [
{ "id": "bcb3…c2a7", "name": "What is your unfair advantage?", "type": "text", "options": [] },
{ "id": "9f21…88d1", "name": "Award category", "type": "select",
"options": [ { "id": "51ac…", "label": "Climate Tech" }, { "id": "0d9e…", "label": "Female Founder" } ] }
]
}
```
`text` questions take a freeform string. `select` takes ONE option label or id; `multi_select` takes an array of them. Option ids are rename-proof, so prefer them over labels. Build your form from this response — it is the source of truth for what the team is asking.
```bash theme={null}
curl https://api.venture.caplia.ai/v1/pipelines \
-H "Authorization: Bearer $CAPLIA_API_KEY"
```
Returns each pipeline's `id`, `name`, and `is_default` (where submissions land when you omit `pipeline_ids`).
```bash theme={null}
curl -X POST https://api.venture.caplia.ai/v1/decks \
-H "Authorization: Bearer $CAPLIA_API_KEY" \
-F "file=@pitch-deck.pdf" \
-F "company_name=Acme Robotics" \
-F "founder_name=Elena Kowalski" \
-F "founder_email=elena@acmerobotics.com" \
-F 'pipeline_ids=["",""]' \
-F 'properties={"bcb3…c2a7":"We own the whole inference stack.","9f21…88d1":"Climate Tech"}'
```
You get a `202` with a `job_id` and a `poll_url` — poll `GET /v1/jobs/{job_id}` until `status` is `completed`. One deal is created per pipeline; `founder_name` and `founder_email` become the company's primary contact (deck analysis fills in role and LinkedIn where the deck reveals them, but never overwrites what you submitted); the `properties` answers appear on the deal and in the team's pipeline columns.