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

# Attachments

> Upload PDF, DOCX, HTML, text, and image files to give the AI additional context or load them into the editor.

# Attachments

Upload files to provide the AI with reference material. The AI can search and reference attachment content when editing your document — or you can load an attachment directly into the editor.

## Supported file types

| Type         | Extensions                               |
| ------------ | ---------------------------------------- |
| PDF          | `.pdf`                                   |
| Word         | `.docx`, `.doc`                          |
| OpenDocument | `.odt`                                   |
| HTML         | `.html`, `.htm`                          |
| Plain text   | `.txt`                                   |
| Rich text    | `.rtf`                                   |
| Markdown     | `.md`                                    |
| LaTeX        | `.tex` (plus `.zip` project archives)    |
| Images       | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` |

Legacy Word (`.doc`), OpenDocument (`.odt`), and Rich Text (`.rtf`) files are normalized into the same rich pipeline as `.docx`, so their headings, tables, and styling carry through.

**LaTeX projects.** A `.tex` file uploads directly. A multi-file LaTeX project — the shape editors export: a root `.tex` plus its `\input` chapters, figures, bibliography, and any custom class files — uploads as a single `.zip`; the root document is detected automatically. Math imports losslessly (every equation keeps its LaTeX source and exports as native Word math), footnotes become real footnotes, bibliographies render with their citations, and source-declared page geometry, font size, and line spacing carry into the editor. Documents built on heavily visual custom classes (many résumé and poster templates) are compiled and imported with their visual layout preserved. A `.zip` that contains no LaTeX root returns a structured error, and anything that can't be represented (for example an EPS figure or a TikZ drawing) is marked with a visible placeholder plus an ingest warning — never silently dropped. Standard BibTeX (`.bib`) bibliographies resolve fully; biblatex-specific flows may degrade to bracketed citation keys plus an ingest warning.

Maximum file size: up to **100 MB** through the pre-signed upload flow (`request_upload_url` → PUT → process) — the path the web app and SDKs use automatically for anything large. Direct inline and multipart uploads are reliable up to about **20 MB**; an API-gateway request-body limit caps direct uploads below the pre-signed ceiling, so send larger files through the pre-signed flow (for files over \~100 KB it is preferable anyway, since bytes never pass through your context window). Oversized or unsupported uploads return a structured error naming the supported formats and the applicable limit.

**Document scale.** A single document can expand into up to **25,000 editable sections** (roughly 6,000 pages), and one chat session can hold up to **30,000 sections** across all of its open documents (roughly 7,500 pages). These are stability limits for the hosted service, not platform caps: there is no hard platform limit on document length or on how many documents you work with in parallel. Crossing a limit returns a structured `413` (`DOCUMENT_TOO_COMPLEX` for a single file, `SESSION_TOO_FULL` for a chat) with `limit_expandable: true` and a contact address; the team is notified automatically and limits are raised on request, typically within a day, via [hello@superdocs.app](mailto:hello@superdocs.app). Larger dedicated deployments are available on Pro and Enterprise.

## Upload a file

Attachments are processed asynchronously. Upload the file, get a `job_id`, then poll for completion. The `job_id` is an opaque UUID — attachment jobs are queried through the same `GET /v1/jobs/{job_id}` path as chat jobs (there's no separate id namespace or endpoint for them).

```bash theme={null}
# 1. Upload
curl -X POST https://api.superdocs.app/v1/attachments/upload \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -F "file=@reference-doc.pdf" \
  -F "session_id=my-session"
```

Response:

```json theme={null}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "reference-doc.pdf",
  "status": "processing",
  "message": "Upload successful. Processing reference-doc.pdf..."
}
```

```bash theme={null}
# 2. Poll for completion
curl https://api.superdocs.app/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
```

When `status` is `"completed"`, the attachment is indexed and available as AI context for that session.

## Check attachment status

```bash theme={null}
curl https://api.superdocs.app/v1/attachments/status/my-session \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
```

## Attachments vs document upload

SuperDocs has two ways to load files — they serve different purposes:

|                    | Attachment (`/v1/attachments/upload`)                                         | Document upload (`/v1/documents/upload`) |
| ------------------ | ----------------------------------------------------------------------------- | ---------------------------------------- |
| **Purpose**        | Reference material for the AI                                                 | Load as the active document              |
| **Processing**     | Async (poll for completion)                                                   | Synchronous (immediate)                  |
| **Editing**        | Read-only — AI can search and reference                                       | Fully editable via chat                  |
| **Multiple files** | Yes — multiple per session                                                    | One active document per session          |
| **Best for**       | Supporting context (e.g., upload a brief, then create a document based on it) | Loading a file you want to edit          |

## Loading an attachment into the editor

After uploading an attachment, you can ask the AI to load it into the editor — making it the active document you can edit:

```python theme={null}
# 1. Upload a file as an attachment
upload = requests.post("https://api.superdocs.app/v1/attachments/upload",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={"file": open("draft.docx", "rb")},
    data={"session_id": "my-session"}
)

# 2. Wait for processing to complete
# ... poll /v1/jobs/{job_id} until status is "completed" ...

# 3. Ask the AI to load it into the editor
response = requests.post("https://api.superdocs.app/v1/chat", headers=HEADERS, json={
    "message": "Load the draft document into the editor",
    "session_id": "my-session"
})
# The AI loads the attachment content as the active document
```

The AI supports two loading modes:

* **Replace** — clears the editor and loads the full attachment (default when the editor is empty)
* **Insert** — adds the attachment content to the existing document (when the editor already has content)

## Image attachments and vision

SuperDocs can **see** the images you attach. The AI visually interprets diagrams, screenshots, photos, charts, scanned documents, and any other image content — and uses what it sees to inform the document it is editing.

Common use cases:

* **Transcribe a screenshot** into the document ("Add the table from this screenshot to my report")
* **Reference a diagram** in generated content ("Write a paragraph describing the architecture in this image")
* **Extract data from a chart** ("Summarize the trends in this chart and add a section about them")
* **Identify objects or text in a photo** ("What does the sign in this photo say? Add it as a quote")
* **Swap an image in the document** ("Replace the cover photo with this attached image", "Use this as the new company logo") — pure URL swap, no AI generation cost

The same `image_attachments` field also drives image generation and editing inside the document — see [Visual content](/features#visual-content--media). Tell the AI **"generate an image of a glass office building at sunrise"** and it creates one and inserts it; click any image in the editor and tell the AI **"brighten this dramatically"** or **"recolor with warm sepia"** and the AI rewrites the bytes.

Images are handled inline with your chat request — no separate upload step is required:

```json theme={null}
{
  "message": "What does this diagram show? Add a section explaining it.",
  "session_id": "my-session",
  "image_attachments": [{
    "id": "img-1",
    "name": "diagram.png",
    "base64Data": "iVBORw0KGgo...",
    "mimeType": "image/png",
    "size": 54321
  }]
}
```

Supported image formats: PNG, JPG/JPEG, GIF, WebP.

## Delete an attachment

```bash theme={null}
curl -X DELETE "https://api.superdocs.app/v1/attachments/ATTACHMENT_ID?session_id=my-session" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
```