---
title: "Trash"
description: "REST endpoints for trash. Bearer-auth required."
section: "API"
group: "REST"
order: 73
---

## GET /api/trash

List trash

List soft-deleted entities across the caller's workspaces. UNIONs over every workspace-scoped soft-deletable entity table. Sortable by `deleted_at` (default), `name`, or `type`. Restore + purge stay on the per-entity routes.

**Query parameters**

- `limit` (optional): Max items per page (1–100, default 100).
- `after` (optional): Keyset cursor — return the page after this row (next page).
- `before` (optional): Keyset cursor — return the page before this row (prev page).
- `ids` (optional): Comma-separated IDs. Narrows results to these IDs within the caller's accessible scope (does not bypass access checks).
- `workspace_id` (optional): Optional narrower — list trash only from this workspace. Without it, lists across every workspace the caller has access to.
- `type` (optional): Filter to a single entity type (matches the ID prefix).
- `search` (optional): Case-insensitive substring match against the row's display field (name / title / subject).

**Response**

```json
{
  "data": [
    {
      "id": "<...>",
      "type": "<...>",
      "name": "<...>",
      "workspaceId": "<...>",
      "deletedAt": "<...>",
      "deletedBy": "<...>",
      "retentionTier": "<...>",
      "purgeAt": "<...>"
    }
  ],
  "pageInfo": {
    "total": "number",
    "hasNextPage": "boolean",
    "hasPreviousPage": "boolean",
    "startCursor": "string",
    "endCursor": "string"
  }
}
```

## DELETE /api/trash

Empty trash

Permanently delete every soft-deleted entity in the caller's accessible workspaces, in one shot. Optional `workspace_id` narrows to a single workspace; optional `type` narrows to a single entity kind. Each row is hard-deleted via the same path as the cleanup worker, so per-entity `*.purged` event handlers run as expected.

**Query parameters**

- `workspace_id` (optional): Optional narrower — only purge trash in this workspace. Without it, purges across every workspace the caller has access to.
- `type` (optional): Filter to a single entity type (matches the ID prefix).

**Response**

```json
{
  "purged": "number",
  "failed": "number"
}
```