---
title: "Get a pre-signed URL to upload large files (.docx/PDF/HTML/MD/RTF) without bloating agent context."
method: POST
path: "/v1/uploads"
tags: ["uploads", "mcp", "uploads"]
---

# Get a pre-signed URL to upload large files (.docx/PDF/HTML/MD/RTF) without bloating agent context.

`POST /v1/uploads`

## Request

- Base URL: `https://api.superdocs.app`
- URL: `https://api.superdocs.app/v1/uploads`
- Auth: HTTP bearer

Returns a short-lived (5-minute) PUT URL plus a ready-to-run `curl_example`. An agent with shell access can run the `curl_example` directly to push the file to cloud storage, so the bytes never pass through its context window; clients without shell execution can surface the command or URL for the caller to run. After upload completes, call process_uploaded_document with the upload_id to trigger parsing. For files <100KB where token cost is trivial, upload_document_base64 still works inline. Max file size: 100 MB. Supported formats: .pdf, .docx, .txt, .rtf, .md, .html, .htm, .tex (plus .zip LaTeX project archives).

## Headers

- `authorization` string, nullable

## Request body

- UploadUrlRequest
  - `filename` string, required: Original filename including extension (e.g. 'contract.docx'). Used downstream for file-type detection.
  - `content_type` string, required: MIME type the agent will PUT with (e.g. 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' for .docx).
  - `size_bytes` integer, required: File size in bytes. Must be > 0 and <= 104857600 (100 MB).
  - `purpose` 'document' | 'attachment' | 'export-html': What this file will be used for. 'document' = the active editable doc; 'attachment' = read-only AI-searchable reference; 'export-html' = HTML payload destined for /v1/documents/export (large-export upload flow, for documents above ~25 MB).

## Response `200`

Successful Response

- UploadUrlResponse
  - `upload_id` string, required
  - `upload_url` string, required
  - `expires_at` string, required
  - `expires_in_seconds` integer, required
  - `max_size_bytes` integer, required
  - `curl_example` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/superdocs/apis/universal-document-ai-api.md) · [All operations](https://skmtc.dev/superdocs/apis/universal-document-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/superdocs/apis/universal-document-ai-api/revisions/37d03122940b?raw)