Files (durable documents)
Every document you create or upload is saved as a durable File. Files outlive the session they were made in: you can list them later, reopen them in a brand-new session, rename them, and archive ones you no longer need. A File is a reusable document, not a copy that disappears when a conversation ends.
This is the layer above sessions. A session is a conversation thread; a File is the document itself. The same File can be opened into different sessions over time.
Everything here works identically over the REST API and the MCP tools.
The mental model
- File — a durable document with a stable id and a title. It persists across sessions until you archive it.
- Session — a conversation thread. Opening a File into a session lets you edit it there; closing it from the session leaves the File untouched.
- Open — attaching a saved File to a session so you can work on it. Open is share-attach, not copy: edits flow back to the one underlying File, so reopening it elsewhere shows your latest changes.
List your Files
curl https://api.superdocs.app/v1/documents \
-H "Authorization: Bearer sk_YOUR_API_KEY"
include_preview=true to also get a small preview_html thumbnail (the first few sections) per document, and page through results with limit and offset. To read one document’s full body, use get_document_detail with include_html=true (below) or open it into a session.
The MCP tool is list_documents.
Get one File’s detail
curl https://api.superdocs.app/v1/documents/{document_id} \
-H "Authorization: Bearer sk_YOUR_API_KEY"
?include_html=true to also get the full document html body back, along with its page_setup and version_id. This is how you read a saved File’s content by id without opening it into a session.
The MCP tool is get_document_detail.
Open a saved File into a session
To keep working on a File, open it into a session. You can open one or more Files at once; the first one you list becomes the focused tab.
curl -X POST https://api.superdocs.app/v1/sessions/my-session/documents/open \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"document_ids": ["doc_2f6c…", "doc_9a1b…"]
}'
open_documents.
Start a session and open Files in one call
If you’re beginning fresh, init_session creates a session and opens one or more saved Files into it in a single request — handy for “reopen my last contract and start editing.”
curl -X POST https://api.superdocs.app/v1/sessions/init \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "contract-review",
"document_ids": ["doc_2f6c…"]
}'
init_session.
Rename a File
curl -X PATCH https://api.superdocs.app/v1/documents/{document_id} \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Q3 Vendor Agreement"}'
rename_document.
Archive a File
Archiving removes a File from your active list. It’s a soft-delete: recoverable, not an immediate permanent erase. Archived Files stay restorable for roughly 30 days before they are purged, after which they’re gone for good.
curl -X DELETE https://api.superdocs.app/v1/documents/{document_id} \
-H "Authorization: Bearer sk_YOUR_API_KEY"
?force=true — archive even if the File is still open in a live session. Without it, archiving a File that another session is actively holding fails with 409 document_in_use (open_in_sessions + a suggested recovery) and leaves it untouched, so you don’t pull a document out from under someone mid-edit — and you always know nothing was archived.?from_session={session_id} — also detach the File from that session as part of the archive.
The MCP tool is archive_document.
archive_document is destructive. It’s a soft-delete — the File is recoverable for about 30 days and then permanently purged. If you expose this to an AI agent, treat it like any other delete: confirm intent before calling it. There is no separate permanent-delete-by-default; archiving is the only removal path, and the ~30-day window is your safety net.
Restore (un-archive) a File
Bring an archived File back to your active list — the clean inverse of archive. It takes the same durable document_id you’d pass to archive, so you can round-trip archive ↔ restore by the same id (no session needed).
curl -X POST https://api.superdocs.app/v1/documents/{document_id}/unarchive \
-H "Authorization: Bearer sk_YOUR_API_KEY"
unarchive_document. (Both are non-billable.)
Files vs sessions vs open documents
| File | Session | Open document |
|---|
| What it is | A durable, reusable document | A conversation thread | A File attached to a session for editing |
| Lifetime | Persists until archived (then ~30-day purge) | Persists across restarts; you choose the id | Lasts while open in the session |
| Closing it | n/a | Delete the session | Removes it from the session only — the File is untouched |
| Editing | Edited via whatever session it’s open in | Holds the chat history | Edits flow back to the underlying File (share-attach, not copy) |
Notes
- Closing a document from a session (see Multi-Document Sessions) does not archive or delete the File — it only detaches it from that session.
- Because open is share-attach, the same File opened in two sessions reflects the same content; there is no fork-on-open. To rewind a specific session’s edits, use revert.
- Files are scoped to the API key owner — your saved documents are only visible to you (or your organization).
