Rewind a chat session to before a specific user message — restores both the document and the conversation in one call.

Rewinds a chat session to the state immediately before a specific user message. The document, conversation history, and supporting context all snap back to that point. The text of the reverted message is returned (compose_text) so the caller can edit and resend it. Messages from the reverted turn forward are soft-archived: hidden from active reads but retained for audit. The original conversation is preserved server-side; the restored conversation becomes the active timeline. Rejects with 409 if the session has a chat job in progress or awaiting approval — wait for the job to settle before reverting. Returns 422 (code 'turn_has_no_restore_point') when the turn recorded no restore point — typically because the message before it did not finish normally; the response carries revertable_turns, a possibly-empty list of turns that can be rewound to.

post/v1/sessions/{session_id}/revert

Request

Base URL: https://api.superdocs.app
URL: https://api.superdocs.app/v1/sessions/{session_id}/revert
Auth: HTTP bearer

Path parameters

session_idstring required

Headers

authorizationstring nullable

Request body

turn_indexinteger required

Turn index of the user message to revert. The text of that message is returned in compose_text so the caller can re-edit and resend it. Every chat row at this turn or later is soft-archived (hidden from active reads but retained for audit).

dry_runboolean nullable

When true, compute the per-document revert diff WITHOUT committing or archiving anything — used to render a preview before the user confirms.

window_idstring nullable

Optional identifier for the client window issuing the revert, used to coordinate concurrent reverts from multiple browser tabs.

Response

Successful Response

session_idstring required

Session identifier.

reverted_to_turninteger required

Turn index that the active conversation now ends at (the AI reply preceding the reverted user message). -1 when the session is reset to its initial empty state (revert from the very first user message).

compose_textstring required

The text of the user message that was reverted. Clients should pre-fill the compose box with this so the user can edit and resend.

editor_actionstring

Client instruction: 'update' to load the restored document, or 'clear' to reset the editor to empty.

archived_turn_countinteger required

Number of chat rows soft-archived by this revert (turns hidden from the UI but retained for audit).

revert_changesobject nullable

Per-document (slug -> change-set) revert diff. Applying these merges the revert onto any concurrent live edits — a conflicting section is surfaced for you to resolve rather than replacing the whole document. On dry_run this is the preview; on a real revert it is what was committed.

revert_conflictsobject nullable

Per-document (slug -> entries) sections whose restore did NOT fully land. TWO classes, told apart by the 'displaced' flag. (1) NOT LANDED ('displaced' absent/false): content another writer committed was preserved instead (reason 'concurrent_edit_preserved' / 'lineage_unknown'), or a removal could not be resolved against the live document; the matching revert_changes entry is annotated 'conflict': true and carries the preserved bytes as new_html (the honest committed state) plus the un-landed restore as restore_html. (2) LANDED IN THE WRONG PLACE ('displaced': true): the content WAS restored but not at its original position — reason 'restored_elsewhere' (it was added at the end of the document because the section it anchors to is gone) or 'position_not_restored' (a concurrent writer's placement won). These carry an empty their_html (nothing of another writer's was preserved, so there is nothing to adopt) plus the raw 'resolution' token, and the matching revert_changes entry is annotated 'displaced': true — never 'conflict', because new_html is still the restored content. (3) NOT SAVED AT ALL ('write_failed': true, operation 'write', chunk_id null): the document's recovery write did not commit — reason 'document_deleted' (archived mid-revert), 'storage_paused' (durable saving paused for this account) or 'write_failed'. Document-level, so there is no matching revert_changes entry; storage still holds the pre-revert content while document_state shows the reverted document, so a client MUST re-read the document before saving again. Null/absent when the revert landed cleanly everywhere.

dry_runboolean

Echoes the request's dry_run: when true nothing was committed/archived — this is a preview only.

redo_checkpoint_idstring nullable

The identifier of the pre-revert state. Revert is non-destructive — passing this back to POST /sessions/{id}/redo (with the same turn_index) restores it and un-archives the rolled-back turns, undoing the revert. Null on a dry-run, and null when the pre-revert state could not be captured — in that case redo_unavailable_reason says which, so absence by design and absence by failure are never the same value.

redo_unavailable_reasonstring nullable

Present ONLY when redo_checkpoint_id is null because the pre-revert state could not be captured (never on a dry-run, where null is by design). The revert itself succeeded and is durable; what is unavailable is the one-step undo of it. Treat a non-null value as: do not attempt redo_revert for this revert — it has no argument to pass.

Changes

No recorded changes to this operation across all 1 revision of this API.