Skip to main content

​
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

Returns your saved documents with their ids, titles, and timestamps. Use the title for display labels. The list is token-light: it never returns a full document body. Pass 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

Returns the File’s title, metadata, and the list of prior chats that used it. Add ?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.
The response returns the session’s document roster (every open document’s id + title + which is focused) so you can render tabs immediately. Because open is share-attach, edits you make in the session update the underlying File — there’s no separate copy to reconcile. The MCP tool is 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.”
The MCP tool is init_session.

​
Rename a File

The new title is what shows up in your File list and on tabs. The MCP tool is 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.
Two optional query params control what happens when the File is currently open somewhere:
  • ?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).
Idempotent — restoring an already-active File is a no-op. The MCP tool is unarchive_document. (Both are non-billable.)

​
Files vs sessions vs open documents

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