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