# Data deletion & export (GDPR)

> Erase or export everything OakData holds for a single visitor - analytics events, replay sessions, and replay chunks - over the secret-key API.

Source: https://oakdata.co/docs/api/gdpr

---

Handle GDPR/CCPA data-subject requests programmatically: **erase** or **export** everything OakData stores for one visitor. Both endpoints live under `https://oakdata.co/api/v1` and are scoped to exactly one project.

## Authentication

Pass your **secret key** (`oak_sec_…`) as a bearer token. Public keys are rejected with `403`. A key resolves to one project, so a request can never touch another project’s data.

**auth**

```bash
curl -X DELETE https://oakdata.co/api/v1/visitors/user_123 \
  -H "Authorization: Bearer oak_sec_xxxxxxxxxxxxxxxxxxxxxxxx"
```

## Delete a visitor’s data

```http
DELETE /api/v1/visitors/{distinctId}
```

Permanently removes, for the authenticated project: every analytics event, every session-replay recording’s metadata, and all of that recording’s rrweb chunks in object storage. The operation is idempotent - calling it again for an already-erased visitor returns the same shape with zero counts.

| Name | Type | Description |
| --- | --- | --- |
| `distinctId` | string | The visitor’s `distinct_id`. Events captured before identity resolution are matched on their `anonymous_id` too, so both pre- and post-identify data are covered. |

> **Irreversible** Deletion is immediate and cannot be undone. Replay chunks are removed from object storage and analytics rows are hard-deleted - there is no soft-delete or recovery window.

Response:

| Name | Type | Description |
| --- | --- | --- |
| `deleted` | boolean | Always `true` on success. |
| `eventsDeleted` | number | Analytics event rows removed. |
| `replaySessionsDeleted` | number | Replay session metadata rows removed. |
| `replayChunksDeleted` | number | rrweb chunk objects removed from storage. |

**response**

```json
{
  "deleted": true,
  "distinctId": "user_123",
  "eventsDeleted": 412,
  "replaySessionsDeleted": 3,
  "replayChunksDeleted": 27
}
```

## Export a visitor’s data

```http
GET /api/v1/visitors/{distinctId}/export
```

Returns a machine-readable JSON document with the raw analytics events and replay session metadata held for the visitor - suitable for fulfilling a data-portability request. Replay chunk blobs themselves are not inlined.

| Name | Type | Description |
| --- | --- | --- |
| `distinctId` | string | The visitor’s `distinct_id`. Events captured before identity resolution are matched on their `anonymous_id` too, so both pre- and post-identify data are covered. |

Response:

| Name | Type | Description |
| --- | --- | --- |
| `distinctId` | string | The visitor this export is for. |
| `exportedAt` | string | ISO timestamp the export was generated. |
| `counts` | object | `{ events, replaySessions }` - totals included in this export. |
| `events` | object[] | Full analytics event rows, ordered oldest-first by timestamp. |
| `replaySessions` | object[] | Replay session metadata rows. |
| `truncated` | boolean | `true` if the visitor has more than 50,000 events and the export was capped. Rare - contact support for a full archive if you hit this. |

**export**

```bash
curl https://oakdata.co/api/v1/visitors/user_123/export \
  -H "Authorization: Bearer oak_sec_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -o user_123.json
```

> **Errors** A missing or invalid key returns `401`; a public key returns `403`. Both endpoints scope strictly to the key’s project.