Skip to main content
Permanently remove a session and everything belonging to it — its objects, threads, graphs, executions and events. Only the closing record survives, the session.deleted event, and only for 24 hours.
This is a hard delete. There is no tombstone, retention window or undo. If you only want to stop a session and freeze it, use Close Session instead — it preserves all contents and can be reversed.

POST /revisions/:id/data/command (Command: delete_session)

Requires the write role on the blob.

Request Body

Response

The command returns as soon as the session is marked deleting. The teardown itself runs in the background — see Asynchronous behavior. If the session had an alias, the response above does not carry it: delete_session releases the alias in the same guarded write that starts teardown, so the name is immediately reusable and no longer resolves to this session.

Errors

The session may be deleted from any live status — open, closing or closed. It does not have to be closed first.

Example

Asynchronous behavior

Deletion happens in stages:
  1. Immediately — the session becomes deleting, session.deleting is emitted, and every mutating operation on it starts returning 409 session_not_open.
  2. Drain — every execution still running in the session is stopped and awaited until terminal. Nothing is purged while work is still running. This ordering is what stops an in-flight execution from writing into a session that is being torn down.
  3. Purge — the session’s objects, thread items, graph elements, executions, execution events and stored events are removed, then the session row itself.
  4. Finally — session.deleted is emitted, after the purge.
Deleting an open session performs this whole sequence as one action; it does not pass through closed and so emits no session.closed along the way. With executions to drain the teardown typically takes tens of seconds.
Executions stopped by a delete end with status stopped. execution.ended is best-effort, so do not wait on it to learn that an execution has ended.

After the delete

Once teardown finishes the session no longer exists:
  • requests referencing it return 403, including download_session_object for objects it contained
  • it no longer appears in List Sessions
  • its per-revision session quota is released
The purge removes the session’s stored events, but session.deleted is written after it and is kept for 24 hours. Within that time get_session_event and list_session_events serve the stream by id, and include_session gives null; an alias no longer resolves. Clients that need a definitive confirmation can read that event, or poll until the session stops resolving. See Types. See Session Lifecycle for the complete model.