Skip to main content
This flow uploads one document, polls for status, then switches to realtime updates.

​
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/scope.pdf",
    "file_name": "claim-123-scope.pdf",
    "xn_address": "restoration-team@example.xn"
  }'
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-scope.pdf",
    "xn_address": "restoration-team@example.xn"
  }'
See Upload a document for Python and Node.js examples that turn a local file into the file_base64 value. Expected shape: 
{
  "document_id": "doc_123",
  "workflow_id": "wf_123",
  "status": "processing",
  "created_at": "2026-04-14T14:30:00Z",
  "status_url": "/status/doc_123",
  "ws_url": "/ws/status"
}

​
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",
  "progress": {
    "ocr": "complete",
    "structure": "in_progress",
    "actions": null,
    "trades": null,
    "categories": null
  },
  "workflow_complete": false,
  "completed_at": null,
  "updated_at": "2026-04-14T14:31:12Z"
}

​
4. 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));
};

​
5. Check remaining credits

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