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

# Legal Holds API

> Preserve your Granola workspace's notes for litigation and investigations.

A legal hold stops Granola from permanently deleting the notes, transcripts and attachments of the people it covers, for as long as the hold is active.

The Legal Holds API lets your eDiscovery or case-management system place, update and release holds, and name the people they cover.

## Getting access

The Legal Holds API is available on Enterprise plans. A workspace admin creates a Legal hold API key in **Settings → Integrations → Legal hold API keys**. A workspace can have up to five active Legal hold keys at a time.

A Legal hold key manages holds and nothing else. It cannot read notes, folders, the audit log, or webhook endpoints.

## What a hold covers

A hold can cover your whole workspace, named custodians, or both:

* `covers_entire_workspace: true` covers every member of the workspace, current and future. It is required when you [create a hold](/api-reference/create-legal-hold), so scope is always an explicit choice, and can be changed later with [update](/api-reference/update-legal-hold). Changing it never touches the custodians the hold names.
* Custodians are named by `email` or by Granola user `id` (`usr_…`), exactly one per entry. They can be set when the hold is created and [added](/api-reference/add-legal-hold-custodians) later. `custodian_count` counts named custodians only.

A custodian must be an active or deactivated member of your workspace — someone who has left stays holdable. Each request accepts up to 100 custodians. If any entry does not resolve to a member, the whole request is rejected with `CUSTODIAN_NOT_IN_WORKSPACE` and nothing is added; the error's `details` lists every entry that failed, not just the first.

Hold names must be unique among your workspace's live holds. Creating or renaming a hold to a name already in use returns `LEGAL_HOLD_NAME_CONFLICT`. A released hold's name can be reused.

## Pagination

Holds are listed newest first, custodians oldest first. `page_size` returns at most 30 items per page. Page on `hasMore` and `cursor`, not on how many items a page contains.

## Errors

| Code                         | Status | Meaning                                                                                                                                              |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LEGAL_HOLD_NOT_FOUND`       | 404    | The hold does not exist in your workspace, or is released and the request would change it. Also returned for a custodian id that is not on the hold. |
| `CUSTODIAN_NOT_IN_WORKSPACE` | 400    | One or more custodians are not active or deactivated members of your workspace.                                                                      |
| `LEGAL_HOLD_NAME_CONFLICT`   | 409    | A live hold in your workspace already has this name.                                                                                                 |

## Next steps

* [`GET /v1/legal-holds`](/api-reference/list-legal-holds) — list holds.
* [`POST /v1/legal-holds`](/api-reference/create-legal-hold) — place a hold.
* [`GET /v1/legal-holds/{hold_id}`](/api-reference/get-legal-hold) — get a hold.
* [`PATCH /v1/legal-holds/{hold_id}`](/api-reference/update-legal-hold) — update a hold.
* [`DELETE /v1/legal-holds/{hold_id}`](/api-reference/release-legal-hold) — release a hold.
* [`GET /v1/legal-holds/{hold_id}/custodians`](/api-reference/list-legal-hold-custodians) — list custodians on a hold.
* [`POST /v1/legal-holds/{hold_id}/custodians`](/api-reference/add-legal-hold-custodians) — name custodians on a hold.
* [`DELETE /v1/legal-holds/{hold_id}/custodians/{custodian_id}`](/api-reference/remove-legal-hold-custodian) — remove a custodian from a hold.