Quickstart

If you are using ChatGPT, Claude, Codex, or another MCP-aware client, start with CapOut MCP. This page covers the direct REST API.

1. Authenticate REST calls

Include your API key as the capout-api-key header.

export CAPOUT_API_KEY="capout_test_your_api_key"

2. Upload a document

The upload API supports both a fetchable url and an inline file_base64 payload.

curl https://api.capout.ai/upload \
  -X POST \
  -H "content-type: application/json" \
  -H "capout-api-key: $CAPOUT_API_KEY" \
  -d '{
    "url": "https://example.com/claims/123/estimate.pdf",
    "file_name": "claim-123-estimate.pdf"
  }'

Inline base64 uploads use the same endpoint with a different request body:

curl https://api.capout.ai/upload \
  -X POST \
  -H "content-type: application/json" \
  -H "capout-api-key: $CAPOUT_API_KEY" \
  -d '{
    "file_base64": "BASE64_PDF_CONTENT",
    "file_name": "claim-123-estimate.pdf"
  }'

See Upload a document for Python and Node.js examples that turn a local file into the file_base64 value. Store the returned document_id and use it to track workflow completion. This is the only public tracking ID; use it in /status/{document_id} and /{document_id}.esx, or follow the returned status_url and download URLs: Expected shape:

{
  "document_id": "doc_123",
  "status": "processing",
  "created_at": "2026-04-14T14:30:00Z",
  "status_url": "/status/doc_123",
  "ws_url": "/ws/status",
  "download_url": "https://api.capout.ai/doc_123.esx",
  "contractor_download_url": "https://api.capout.ai/doc_123.esx?profile=contractor",
  "carrier_download_url": "https://api.capout.ai/doc_123.esx?profile=carrier"
}

Store these clean CapOut download URLs. They are stable, even though the private S3 URL they redirect to is short-lived. Opening one before export completion returns 409.

3. Poll the document status

curl https://api.capout.ai/status/doc_123 \
  -H "capout-api-key: $CAPOUT_API_KEY"

Typical response while work is still running:

{
  "document_id": "doc_123",
  "status": "processing",
  "workflow_complete": false,
  "completed_at": null,
  "updated_at": "2026-04-14T14:31:12Z"
}

After a successful export, the status response includes the same links:

{
  "document_id": "doc_123",
  "status": "exported",
  "terminal": true,
  "workflow_complete": true,
  "export": {
    "status": "COMPLETED",
    "claims_used": 1,
    "download_url": "https://api.capout.ai/doc_123.esx",
    "contractor_download_url": "https://api.capout.ai/doc_123.esx?profile=contractor",
    "carrier_download_url": "https://api.capout.ai/doc_123.esx?profile=carrier"
  }
}

4. Download an ESX file

The default link downloads the Contractor (8D) file. Use the Carrier link when you need the 5L profile:

# Contractor (default)
curl -L "https://api.capout.ai/doc_123.esx" \
  -H "capout-api-key: $CAPOUT_API_KEY" \
  -o estimate-contractor.esx

# Carrier
curl -L "https://api.capout.ai/doc_123.esx?profile=carrier" \
  -H "capout-api-key: $CAPOUT_API_KEY" \
  -o estimate-carrier.esx

The download route requires the same capout-api-key as upload. The document must belong to that key’s organization; never put the key in the URL or query string.

5. Switch to realtime updates

Mint a short-lived token, then connect with SSE or WebSocket.

curl https://api.capout.ai/ws/token \
  -X POST \
  -H "capout-api-key: $CAPOUT_API_KEY"

Browser-friendly SSE example:

const tokenResponse = await fetch("https://api.capout.ai/ws/token", {
  method: "POST",
  headers: {
    "capout-api-key": process.env.CAPOUT_API_KEY,
  },
}).then((res) => res.json());

const streamUrl = new URL(tokenResponse.sse_url, "https://api.capout.ai");
streamUrl.searchParams.set("token", tokenResponse.token);
streamUrl.searchParams.append("document_id", "doc_123");

const source = new EventSource(streamUrl);

source.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};

6. Check remaining claims

curl https://api.capout.ai/claims \
  -H "capout-api-key: $CAPOUT_API_KEY"

Get Started

Workflows

MCP

1. Authenticate REST calls

2. Upload a document

3. Poll the document status

4. Download an ESX file

5. Switch to realtime updates

6. Check remaining claims

​1. Authenticate REST calls

​2. Upload a document

​3. Poll the document status

​4. Download an ESX file

​5. Switch to realtime updates

​6. Check remaining claims

1. Authenticate REST calls

2. Upload a document

3. Poll the document status

4. Download an ESX file

5. Switch to realtime updates

6. Check remaining claims