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

# Conventions

> Base URL, lists, safe retries, request ids and text you shouldn't trust.

## Base URL and format

* REST: `https://api.captureflow.ai/v1`. Requests and responses are JSON (`Content-Type: application/json`); request bodies are 100 KB at most ([`body_too_large`](https://docs.captureflow.ai/api/errors#body_too_large)).
* Every object has an `object` field naming its kind (`idea`, `input`, `post`, `proposal`...).
* `GET /v1/health` answers without a key: `{ "status": "ok", "version": "v1" }`.
* The OpenAPI 3.1 description: `https://api.captureflow.ai/v1/openapi.json`.
* Browsers may call the REST API from any origin with a bearer credential (no cookies).

## Lists and pagination

List operations take `limit` (1 to 100, default 25) and `cursor`, and answer:

```json theme={null}
{ "object": "list", "data": [ ... ], "has_more": true, "next_cursor": "eyJvIjoyNX0" }
```

Pass `next_cursor` back as `cursor` for the next page, until `has_more` is `false`. Paging stops after 10,000 items; narrow the list with its filters to reach older ones.

## Safe retries (`Idempotency-Key`)

Calls that create or change something accept an `Idempotency-Key` header (over MCP: the `idempotency_key` argument). Use a new unique value (a UUID) per action, and the same value when retrying it.

* Kept for 24 hours, 1 to 255 visible ASCII characters.
* A retry with the same key and the same request returns the first answer instead of doing it twice. The replay has `Idempotent-Replayed: true` and carries only the ids and statuses (`object`, `id`, `status`, `app_url`, `approval_url`...); read the object for the rest.
* The same key with a different request: [`idempotency_conflict`](https://docs.captureflow.ai/api/errors#idempotency_conflict). The first call still running: [`idempotency_in_progress`](https://docs.captureflow.ai/api/errors#idempotency_in_progress).
* A failed call frees its key.
* `POST /inputs/uploads/{id}/url` and `POST /inputs/uploads/{id}/complete` don't take one: they are safe to repeat on their own.

## Request ids

Every response has an `X-Request-Id` header, also in error bodies as `request_id` (over MCP: `_meta.request_id`). Quote it when contacting support.

## Text you shouldn't trust

Text that comes from outside (transcripts, imported web pages, documents, drafts the agent wrote from them) is returned wrapped:

```json theme={null}
{ "untrusted_content": true, "source": "input.transcript", "text": "...", "truncated": false }
```

`source` says where the text comes from (`input.transcript`, `post.body`, `agent.linkedin`...). Long texts are cut at 4,000 characters (`truncated: true`); `GET /v1/inputs/{id}?full=true` returns up to 50,000.

If your app passes it to a language model, treat it as data, never as instructions: it may contain text written to steer an AI (prompt injection).

## Pausing changes

During maintenance, changes may be paused while reads keep working: calls that change something answer [`writes_unavailable`](https://docs.captureflow.ai/api/errors#writes_unavailable) (503), and MCP clients see only the read tools.


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