Skip to main content

​
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).
  • 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:
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. The first call still running: 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:
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 (503), and MCP clients see only the read tools.