---
title: "Get a pre-signed URL to download an exported document without proxying through the agent."
method: POST
path: "/v1/downloads"
tags: ["uploads", "mcp", "downloads"]
---

# Get a pre-signed URL to download an exported document without proxying through the agent.

`POST /v1/downloads`

## Request

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

Returns a short-lived (15-minute) GET URL plus a ready-to-run `curl_example`. An agent with shell access can run the `curl_example` directly to save the exported file to the working directory, so the bytes never pass through its context window; clients without shell execution (or callers who only want the link) can use the signed URL directly. Generates the document in the requested format and returns a time-limited signed download URL. Specify format as 'pdf', 'docx', 'html', 'markdown', or 'txt' (legacy 'doc' also accepted).

## Headers

- `authorization` string, nullable

## Request body

- DownloadUrlRequest
  - `session_id` string, required: Session ID whose current document should be exported and packaged for download.
  - `format` 'docx' | 'pdf' | 'html' | 'markdown' | 'txt' | 'doc': Export format (docx, pdf, html, markdown, txt).
  - `filename` string, nullable: Optional Content-Disposition filename for the download (without extension). Auto-detected from the document's first heading if not provided.
  - `options` ExportOptions: User-facing export customisation (page size, orientation, margins, filename, watermark). Sent on every export request.
    - `paper_size` 'A4' | 'Letter' | 'A3' | 'Legal': Page size for DOCX/PDF/legacy .doc. HTML/MD/TXT exports ignore.
    - `orientation` 'portrait' | 'landscape': Page orientation for DOCX/PDF/legacy .doc.
    - `margins` 'narrow' | 'normal' | 'wide' | 'custom': Page margins preset. 'narrow' = 0.5in, 'normal' = 1.0in, 'wide' = 1.5in. 'custom' uses custom_margins_inches.
    - `custom_margins_inches` object, nullable: Required when margins='custom'. Each value 0.25-3.0 inches.
    - `filename` string, nullable: Custom filename (no extension). Auto-detected from first <h1> if unset.
    - `embed_images` boolean: HTML export only. When True, images are base64-embedded for offline portability (raises size cap to 150 MB). When False, images are referenced by URL (smaller file, online-only).
    - `watermark_text` string, nullable: PDF only. Optional text watermark overlaid on every page.
    - `watermark_opacity` number: PDF watermark opacity, 0.05-1.0.
    - `fidelity` 'strict' | 'compat', nullable: Export fidelity. 'strict' (server default) renders only the formatting the document carries — no imposed table widths/borders (except visual defaults on fully unstyled tables), overflow-only clamping, highlight colors honored. 'compat' reproduces the legacy normalized output.

## Response `200`

Successful Response

- DownloadUrlResponse
  - `download_url` string, required
  - `expires_at` string, required
  - `expires_in_seconds` integer, required
  - `curl_example` string, required
  - `filename` string, required
  - `format` 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)