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

# Staged Uploads

> Use capout_create_upload_url and capout_process_staged_upload for local PDFs because the CapOut MCP is hosted remotely.

Use the staged upload flow for PDFs that exist on the local machine or workspace. CapOut MCP is hosted remotely, so it cannot read those files directly.

This is an MCP-only workflow. It is separate from the public REST `POST /upload` API.

Staged uploads support PDFs up to `50 MiB`.

## Rate limit

`capout_create_upload_url` is limited to `10` signed upload URLs per minute per authenticated API key.

For folder runs, batch runs, or subagent-heavy flows, create at most 10 staged upload URLs at a time before requesting more.

## Step 1: create a friendly upload URL

```json theme={null}
{
  "tool": "capout_create_upload_url",
  "arguments": {
    "file_name": "broderick.pdf",
    "file_size_bytes": 271456
  }
}
```

Typical response:

```json theme={null}
{
  "content_type": "application/pdf",
  "curl_command": "curl -X PUT -H 'content-type: application/pdf' --upload-file 'broderick.pdf' 'https://api.capout.ai/u/Shingle-Gutter-Nails-Felt-Flashing'",
  "expires_in_seconds": 900,
  "file_name": "broderick.pdf",
  "friendly_upload_url": "https://api.capout.ai/u/Shingle-Gutter-Nails-Felt-Flashing",
  "headers": {
    "content-type": "application/pdf"
  },
  "method": "PUT",
  "next_step": "Run curl_command locally, then call capout_process_staged_upload with s3_path, file_name, xn_address, and profile_code.",
  "request_id": "req_123",
  "s3_path": "protected/owner/pdf-intake/req_123/123-broderick.pdf"
}
```

The MCP does not expose raw presigned S3 upload URLs here. It returns a short CapOut upload URL plus a ready-to-run `curl_command`.

## Step 2: upload the PDF locally

Run the returned command on the same machine where the PDF exists:

```bash theme={null}
curl -X PUT \
  -H 'content-type: application/pdf' \
  --upload-file 'broderick.pdf' \
  'https://api.capout.ai/u/Shingle-Gutter-Nails-Felt-Flashing'
```

## Step 3: process the staged upload

```json theme={null}
{
  "tool": "capout_process_staged_upload",
  "arguments": {
    "file_name": "broderick.pdf",
    "s3_path": "protected/owner/pdf-intake/req_123/123-broderick.pdf",
    "xn_address": "matt@capout.prod",
    "profile_code": "5L"
  }
}
```

Successful response:

```json theme={null}
{
  "document_id": "b9cf4ef8-9fa3-441b-b0d3-990bee7fbcce",
  "message": "CapOut accepted the document for background processing. Keep polling with capout_wait_for_document or capout_document_status until terminal is true."
}
```

## What to do next

After `capout_process_staged_upload` succeeds, keep polling until completion with [Status and Waiting](/mcp/tools/status-and-waiting).