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

# Purge Data

> Delete user or connection data with vault key destruction.

## `POST /api/purge`

Permanently deletes user or connection data. Supports two modes: purge all data for a user, or purge a single connection.

Deletion is **irreversible** — vault encryption keys are destroyed, making stored credentials mathematically irrecoverable.

## Request

**Headers**

| Header          | Value                    |
| --------------- | ------------------------ |
| `Authorization` | `Bearer YOUR_APP_SECRET` |
| `Content-Type`  | `application/json`       |

### Mode 1: Purge all user data

Deletes all connections and conversations for a user within your app.

```json theme={null}
{
  "appId": "app_yourapp",
  "userRef": "user_123"
}
```

### Mode 2: Purge a single connection

Deletes one specific connection and its conversations.

```json theme={null}
{
  "appId": "app_yourapp",
  "connectionId": "CONNECTION_ID"
}
```

| Field          | Type     | Required | Description                                         |
| -------------- | -------- | -------- | --------------------------------------------------- |
| `appId`        | `string` | Yes      | Your app identifier                                 |
| `userRef`      | `string` | One of   | Your internal user identifier (purge all user data) |
| `connectionId` | `string` | One of   | Specific connection UUID (purge single connection)  |

<Note>
  Provide either `userRef` or `connectionId`, not both.
</Note>

## What gets deleted

For each affected connection:

1. **Vault key** destroyed (`vault_destroy`) — encryption key deleted from `connection_keys`
2. **Browserbase context** released (if present)
3. **Connection** set to `status: 'revoked'`, `enc_blob: null`
4. **Storage files** removed from Supabase Storage bucket
5. **Conversations** hard-deleted

## Response

```json theme={null}
{
  "ok": true,
  "connectionsRevoked": 2,
  "conversationsDeleted": 142,
  "deletedAt": "2026-09-25T16:00:00Z"
}
```

| Field                  | Type      | Description                            |
| ---------------------- | --------- | -------------------------------------- |
| `ok`                   | `boolean` | Always `true` on success               |
| `connectionsRevoked`   | `number`  | Number of connections set to `revoked` |
| `conversationsDeleted` | `number`  | Total conversations deleted            |
| `deletedAt`            | `string`  | ISO 8601 timestamp of deletion         |

## Webhooks

| Purge mode                        | Webhook event        | Payload                                                                  |
| --------------------------------- | -------------------- | ------------------------------------------------------------------------ |
| User purge (`userRef`)            | `data.deleted`       | `{ userRef, providers, connectionIds, conversationsDeleted, deletedAt }` |
| Connection purge (`connectionId`) | `connection.deleted` | `{ connectionId, provider, conversationsDeleted, deletedAt }`            |

## Errors

| Status | Error                                     | Cause                                    |
| ------ | ----------------------------------------- | ---------------------------------------- |
| 400    | `Missing appId`                           | `appId` field not provided               |
| 400    | `Provide either userRef or connectionId`  | Neither field provided                   |
| 400    | `Invalid JSON body`                       | Request body is not valid JSON           |
| 401    | `Missing or invalid Authorization header` | Missing `Bearer` prefix                  |
| 401    | `Invalid API key`                         | Wrong or missing app secret              |
| 404    | `App not found`                           | App ID doesn't exist                     |
| 404    | `User not found`                          | No user with this `userRef` for your app |
| 404    | `Connection not found`                    | Connection ID doesn't exist              |
| 404    | `Connection does not belong to this app`  | Connection belongs to a different app    |
| 405    | `Method not allowed`                      | Must use `POST`                          |