> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Session

Permanently remove a session and everything belonging to it — its objects, threads, graphs,
executions and events.

<Warning>
  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](/blob-types/workflow/operations/close-session) instead —
  it preserves all contents and can be reversed.
</Warning>

## **POST** `/revisions/:id/data/command` (Command: `delete_session`)

Requires the **write** role on the blob.

### Request Body

| Parameter    | Type   | Required | Description                     |
| :----------- | :----- | :------- | :------------------------------ |
| `engine`     | string | Yes      | Must be `workflow_blobhub`.     |
| `command`    | string | Yes      | Must be `delete_session`.       |
| `session_id` | string | Yes      | The ID or alias of the session. |

### Response

| Parameter | Type   | Description                                   |
| :-------- | :----- | :-------------------------------------------- |
| `session` | object | The session, with `status` set to `deleting`. |

The command returns as soon as the session is marked `deleting`. The teardown itself runs in the
background — see [Asynchronous behavior](#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

| Status | Error                      | Cause                                         |
| :----- | :------------------------- | :-------------------------------------------- |
| 409    | `session_already_deleting` | A delete is already in progress.              |
| 403    | `forbidden`                | Missing write access, or the session is gone. |

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

### Example

<CodeGroup>
  ```json Request theme={null}
  {
    "engine": "workflow_blobhub",
    "command": "delete_session",
    "session_id": "sess_001"
  }
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "session": {
      "id": "sess_001",
      "status": "deleting"
    }
  }
  ```
</CodeGroup>

## 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.

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.

<Note>
  Executions stopped by a delete end with status `stopped` and do **not** emit `execution_ended` —
  that event is reserved for executions that complete on their own.
</Note>

## 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](/blob-types/workflow/operations/list-sessions)
* its per-revision session quota is released

Because the stored event stream is purged along with everything else, the terminal `session_deleted`
event is delivered over the realtime WebSocket API only — it cannot be read back afterwards with
`list_session_events`. Clients that need a definitive confirmation should watch for that event, or
poll until the session stops resolving.

See [Session Lifecycle](/blob-types/workflow/workflows/session-lifecycle) for the complete model.