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

# Deleting Data

> How to delete sessions, workspaces, and conclusions — and what survives each

Deletion in Honcho is **permanent and cannot be undone**. There is no soft
delete, no trash, and no restore.

## What can be deleted

| Resource | Endpoint | Behavior |
| - | - | - |
| Session | `DELETE /v3/workspaces/{workspace_id}/sessions/{session_id}` | `202` — cascade runs in the background |
| Workspace | `DELETE /v3/workspaces/{workspace_id}` | `202` — cascade runs in the background |
| Conclusion | `DELETE /v3/workspaces/{workspace_id}/conclusions/{conclusion_id}` | `204` — immediate |
| Webhook endpoint | `DELETE /v3/workspaces/{workspace_id}/webhooks/{endpoint_id}` | Immediate |

**Peers and individual messages cannot be deleted.** To remove a peer's data,
delete the sessions it participated in, then delete its remaining conclusions
(see [Conclusions outlive their sessions](#conclusions-outlive-their-sessions)).
To remove a peer from one conversation without deleting anything, use
[remove peers from session](https://honcho.dev/docs/v3/api-reference/endpoint/sessions/remove-peers-from-session.md)
instead.

## Deleting a session

```bash theme={null}
curl -X DELETE "$HONCHO_URL/v3/workspaces/my-app/sessions/session-1" \
  -H "Authorization: Bearer $HONCHO_API_KEY"
```

The session is marked inactive immediately and the endpoint returns `202
Accepted`. The cascade — messages, message embeddings, queued reasoning work,
session-scoped conclusions, and peer associations — is processed in the
background with retries.

Because the work is asynchronous, a `202` means *accepted*, not *finished*. The
session drops out of session listings right away, but its messages and
conclusions drain afterwards. Deletion tasks are internal infrastructure work
and do **not** appear in
[queue status](https://honcho.dev/docs/v3/documentation/features/advanced/queue-status.md) counts, so
there is no endpoint that reports when the cascade has finished.

```python Python theme={null}
session.delete()
```

```typescript TypeScript theme={null}
await session.delete();
```

## Deleting a workspace

A workspace can only be deleted once it has **no active sessions**. Deleting a
workspace that still has sessions returns `409 Conflict`:

```json theme={null}
{"detail": "Cannot delete workspace 'my-app': active session(s) remain. Delete all sessions first."}
```

The correct order is:

1. List the workspace's sessions — `POST /v3/workspaces/{workspace_id}/sessions/list`
2. Delete each session — `DELETE /v3/workspaces/{workspace_id}/sessions/{session_id}`
3. Delete the workspace — `DELETE /v3/workspaces/{workspace_id}`

Step 2 returns `202`, so the session deletions are still draining when step 3
runs. That is fine: a session is marked inactive synchronously, so the workspace
delete stops returning `409` as soon as the deletes are accepted. Any session
created after the workspace deletion is accepted is cascade-deleted too.

```python Python theme={null}
# Materialize the list first — deleting shifts the pagination window
for session in list(honcho.sessions()):
    session.delete()

honcho.delete_workspace("my-app")
```

```typescript TypeScript theme={null}
// Materialize the list first — deleting shifts the pagination window
const sessions = [];
for await (const session of await honcho.sessions()) sessions.push(session);
for (const session of sessions) await session.delete();

await honcho.deleteWorkspace("my-app");
```

Deleting a workspace removes every peer, session, message, conclusion,
collection, embedding, webhook endpoint, and queued task belonging to it.

## Conclusions outlive their sessions

This is the most common surprise. Deleting a session does **not** erase
everything Honcho learned in it.

* **Explicit conclusions** — direct facts drawn from messages — are tied to the
  session they came from and are deleted with it.
* **Derived conclusions** (deductive, inductive, contradiction) are consolidations
  that may draw on several sessions. They are stored at the workspace level with
  no owning session, so they survive session deletion and stay in the peer's
  [representation](https://honcho.dev/docs/v3/documentation/core-concepts/representation.md).

To remove those, list and delete them directly:

```python Python theme={null}
for conclusion in alice.conclusions.list():
    alice.conclusions.delete(conclusion.id)
```

```typescript TypeScript theme={null}
for (const conclusion of await alice.conclusions.list()) {
  await alice.conclusions.delete(conclusion.id);
}
```

Deleting the whole workspace removes conclusions at every level and needs no
follow-up.

## Permissions

Session and workspace deletion accept any key scoped to that workspace — an
admin key is not required. Deleting a session additionally accepts a
session-scoped key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.