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. 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).

# 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:

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

# 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

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:

# 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. 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:

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

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

Getting Started

Capabilities

Account & Billing

Core Concepts

Guides

MCP Integration

Errors & Limits

Code Examples

Attachments

Attachments

Supported file types

Upload a file

Check attachment status

Attachments vs document upload

Loading an attachment into the editor

Image attachments and vision

Delete an attachment

​Attachments

​Supported file types

​Upload a file

​Check attachment status

​Attachments vs document upload

​Loading an attachment into the editor

​Image attachments and vision

​Delete an attachment

Attachments

Supported file types

Upload a file

Check attachment status

Attachments vs document upload

Loading an attachment into the editor

Image attachments and vision

Delete an attachment