# Trash and bulk actions

Move people and records to the Trash one at a time or in bulk, restore them, and delete them for good.


Deleting a person or a record moves it to the Trash, as in the app. From there you can restore it or delete it permanently.

## Move to the Trash

One at a time:

```bash
curl -X DELETE https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/records/RECORD_ID \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: trash-record-1"
```

`DELETE .../people/{person_id}` works the same way. A record that is still processing returns `409 conflict`.

In bulk, up to 100 ids per request:

```bash
curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/people/delete \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: trash-people-1" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["PERSON_ID_1", "PERSON_ID_2"]}'
```

`POST .../records/delete` takes the same body for records.

## Bulk requests are all or nothing

Every bulk request in the API (Trash, folders, tags and notifications) follows the same rules:

- At most 100 ids, and every id must be a UUID.
- If any id is not in the workspace, belongs to someone else, or is in the wrong state (for example already in the Trash), the whole request returns `404 not_found` and nothing changes.
- A bulk request counts as one request against your [rate limit](/developers/docs/rate-limits).

## List the Trash

```bash
curl "https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/trash?type=people" \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

Items come newest deletion first, each with `id`, `type` (`person` or `record`), `name` and `deleted_at`. Leave out `type` to list both.

## Restore

```bash
curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/trash/restore \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: restore-1" \
  -H "Content-Type: application/json" \
  -d '{"people_ids": ["PERSON_ID"], "record_ids": ["RECORD_ID"]}'
```

Send at least one id, at most 100 in total. A restored person brings their trashed linked records back with them, so `restored_record_ids` can list more records than you sent.

Every id is checked before anything changes. A request with both people and records restores the records first, then the people. If a database error stops the second step, you still get `200` listing only what was restored; send the rest again.

## Delete permanently

`POST .../trash/delete` takes the same body and deletes the items for good, including record image files. It only accepts items that are already in the Trash. **This cannot be undone.**

People who were merged into someone stay in the Trash. To delete the person they were merged into, include them in the same request (or restore and unmerge them first); otherwise the request returns `409 conflict` with their ids in `details.merged_person_ids`, and nothing is deleted.

Canonical: https://kleiobase.com/developers/docs/trash