> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdocs.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Sessions
> Sessions persist conversation history and document state across requests. You choose the session ID.
# 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.
```bash theme={null}
# First request — starts a new session
curl -X POST https://api.superdocs.app/v1/chat \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Add an introduction section",
"session_id": "project-proposal-v1",
"document_html": "Project Proposal
"
}'
# Second request — continues the same session
curl -X POST https://api.superdocs.app/v1/chat \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Now add a budget section",
"session_id": "project-proposal-v1",
"document_html": "...updated HTML from previous response...
"
}'
```
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](/concepts/documents#sending-document-html).
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](/guides/multi-document).
## 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](#delete-a-session) below). Note that archived durable Files follow their own lifecycle and are purged about 30 days after archiving; see [Files](/concepts/files).
## List sessions
```bash theme={null}
curl https://api.superdocs.app/v1/sessions \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
Returns session IDs, message counts, timestamps, and a preview of the first message.
## Load session history
```bash theme={null}
curl https://api.superdocs.app/v1/sessions/project-proposal-v1/history \
-H "Authorization: Bearer sk_YOUR_API_KEY"
```
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.
```bash theme={null}
curl -X POST https://api.superdocs.app/v1/sessions/project-proposal-v1/revert \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"turn_index": 4}'
```
`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:
```
session_id: "user_123_draft-contract"
session_id: "user_456_meeting-notes"
```
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](https://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.