Skip to main content

​
Sessions

A session holds your conversation history and document state. Reuse a session ID to pick up where you left off.

​
How sessions work

You choose the session_id — any string you want. The API stores the conversation and document state for that session.
The AI remembers the full conversation. On the second request, it knows about the introduction it just wrote.
You don’t have to re-send document_html on every turn. Once the session holds a document the server keeps it, so a follow-up can send just the message (the example above re-sends it to also sync any edits the client made). Re-send the HTML only to replace the document or to sync edits you made outside chat. See Documents.
A session can also hold multiple open documents at once — each with its own document_id, with one document focused at a time. Chat turns target the focused document unless you pass document_id (or name a document in the message). See the Multi-Document Sessions guide.

​
Persistence

Sessions persist across server restarts. You can close your browser, come back tomorrow, and resume with the same session_id. Sessions do not expire. There is no retention window or time-based cleanup: a session from six months ago is just as resumable as one from this morning. Conversation history and document state remain available until you delete the session yourself (see Delete a session below). Note that archived durable Files follow their own lifecycle and are purged about 30 days after archiving; see Files.

​
List sessions

Returns session IDs, message counts, timestamps, and a preview of the first message.

​
Load session history

The response includes:
  • messages — Full conversation history. Each message carries turn_index (the position in the session) and checkpoint_id (a marker used by the revert endpoint; null for older messages recorded before the revert feature shipped).
  • document_state — Current document HTML, version ID, and attachment list
  • editor_action — What to do with the document: "update" (load the HTML), "clear" (reset), or "keep" (no change)

​
Revert a session to a previous message

Rewind both the chat and the document to the state immediately before a specific user message.
turn_index is the position of the user message you want to undo. Pass it from a messages[i].turn_index you got back from the history endpoint above. The response gives you:
  • compose_text — The text of the user message that was reverted. Useful to pre-fill a compose box so the user can edit and resend.
  • reverted_to_turn — The turn the conversation now ends at (the previous AI reply), or -1 if the session was reset to its initial empty state.
  • document_state + editor_action — Same shape as the history endpoint. Apply them to your editor.
  • archived_turn_count — How many rows were soft-archived.
What happens:
  • The session is restored to the state at that point in the conversation — both the chat history and the document are rewound to the previous AI reply. Messages and document state from the reverted point onward are retained for audit but hidden from active reads.
  • Subsequent messages on this session continue from that restored point. There is no timeline-switcher in the API today — the restored timeline becomes the only visible one.
  • If the session has a chat job currently running (in progress or awaiting approval), the revert call returns 409. Wait for the job to settle or cancel it first.
  • If the user message predates the revert feature (its checkpoint_id is null), the call returns 422. Older sessions can still be loaded; only their per-message revert is unavailable.

​
Session isolation

Sessions are isolated per user. Your sessions are never visible to other users.

​
B2B session management

If you’re serving multiple end users through a single API key, manage session IDs per user on your end. For example, prefix session IDs with your user’s identifier:
This keeps each user’s conversations and documents separate.

​
Delete a session

Session deletion lives at /v1/users/me/sessions/{id}, which is part of the web-app account surface — it accepts web-app session tokens only and rejects sk_ / lce_ API keys with a 401. Delete sessions from the browser at use.superdocs.app → Settings. From an API-key context you don’t need to delete sessions: they persist server-side but are never billed unless used, so simply stop reusing a session_id to retire it. Each user’s sessions stay isolated regardless.