Download ESX Files

Every accepted upload returns stable links for both generated ESX profiles:

{
  "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"
}

The links are safe to store in your application. The private S3 signatures behind them are not.

Choose a profile

Link	ESX profile
`/{document_id}.esx`	Contractor (`8D`), the default
`/{document_id}.esx?profile=contractor`	Contractor (`8D`)
`/{document_id}.esx?profile=carrier`	Carrier (`5L`)

CapOut generates both files for every successful export. The deprecated upload field profile_code does not choose which artifact is generated or downloaded.

Download from an authenticated client

Send the same organization-scoped capout-api-key used for upload, status, and document history. Do not put the key in the URL or a query parameter.

# 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 URL alone does not grant access. A valid key for the document’s organization is required each time CapOut issues a fresh signed redirect.

How the stable redirect works

Your integration stores the clean api.capout.ai URL returned by CapOut.
The client requests the link with capout-api-key.
CapOut validates the key and verifies that the durable document belongs to its organization.
CapOut forwards the caller’s key to the frontend workflow action, which independently checks access and signs the selected Contractor or Carrier artifact.
The route returns a non-cached 307 redirect to a signed private S3 URL.
The S3 signature expires after 15 minutes, while the original CapOut link remains stable and can issue another fresh redirect later.

Do not copy the redirected S3 URL into your database or send it as the durable link. Always retain the clean CapOut URL.

Readiness and errors

The clean links are returned immediately after upload so you can store them with the job. They become downloadable only after ESX generation completes.

Status	Meaning
`307`	Export is ready; follow the redirect to download it
`401`	`capout-api-key` is missing or invalid
`404`	Document is unknown or inaccessible, or the requested profile artifact was not found
`409`	Export is still processing or otherwise not ready
`422`	`profile` is not `contractor` or `carrier`
`502`	CapOut could not refresh a valid signed artifact URL
`503`	Durable download lookup is temporarily unavailable

Wait for export.completed, or for GET /status/{document_id} to report a completed export, before presenting the link as ready. A client that opens it early can retry after receiving 409.

Where the links appear

The same stable URLs are available from:

POST /upload
GET /status/{document_id} under export
GET /documents under each document’s export
realtime export.completed events
CapOut MCP processing, status, and waiting tools

Get Started

Workflows

MCP

Choose a profile

Download from an authenticated client

How the stable redirect works

Readiness and errors

Where the links appear

​Choose a profile

​Download from an authenticated client

​How the stable redirect works

​Readiness and errors

​Where the links appear

Choose a profile

Download from an authenticated client

How the stable redirect works

Readiness and errors

Where the links appear