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 |
| HTML | .html, .htm |
| Plain text | .txt |
| Rich text | .rtf |
| Markdown | .md |
| Images | .png, .jpg, .jpeg, .gif, .webp |
Legacy .doc files are not supported. Convert to .docx first.
Upload a file
Attachments are processed asynchronously. Upload the file, get a job_id, then poll for completion.
# 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"
{
"job_id": "att_abc123",
"filename": "reference-doc.pdf",
"status": "processing",
"message": "Upload successful. Processing reference-doc.pdf..."
}
# 2. Poll for completion
curl https://api.superdocs.app/v1/jobs/att_abc123 \
-H "Authorization: Bearer sk_YOUR_API_KEY"
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
- 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”)
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
}]
}
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"
