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. 
# 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": "<h1>Project Proposal</h1>"
  }'

# 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": "<div data-chunk-id=\"...\">...updated HTML from previous response...</div>"
  }'
The AI remembers the full conversation. On the second request, it knows about the introduction it just wrote. 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.

​
List sessions

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

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. 
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 server-side:
  • The chat session is forked at the checkpoint stored on the previous AI reply. The original branch (the messages and document state from the reverted point onward) is kept in the database for audit but hidden from active reads.
  • Subsequent messages on this session continue from the fork point. There is no branch-switcher in the API today — the new branch becomes the only visible timeline.
  • 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 (no checkpoint marker recorded), 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

curl -X DELETE https://api.superdocs.app/v1/users/me/sessions/project-proposal-v1 \
  -H "Authorization: Bearer sk_YOUR_API_KEY"