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

# Shelves

> Shelf lifecycle, review mode behavior, and endpoint availability by status.

A shelf is the filesystem resource created from an uploaded document.

## Lifecycle

| Status        | Meaning                                  |
| ------------- | ---------------------------------------- |
| `uploading`   | Upload accepted and queued               |
| `parsing`     | Source content extraction in progress    |
| `structuring` | Filesystem layout generation in progress |
| `verifying`   | Output checks in progress                |
| `review`      | Waiting for approval (review mode only)  |
| `ready`       | Finalized and available                  |
| `failed`      | Processing failed; retry available       |

## Endpoint availability by status

| Endpoint                                                     | `uploading/parsing/structuring/verifying` | `review` | `ready` | `failed` |
| ------------------------------------------------------------ | ----------------------------------------- | -------- | ------- | -------- |
| `GET /v1/shelves/{shelfPublicId}`                            | Yes                                       | Yes      | Yes     | Yes      |
| `GET /v1/shelves/{shelfPublicId}/tree`                       | No                                        | Yes      | Yes     | No       |
| `GET /v1/shelves/{shelfPublicId}/files/*`                    | No                                        | Yes      | Yes     | No       |
| `GET /v1/shelves/{shelfPublicId}/archive-url`                | No                                        | Yes      | Yes     | No       |
| `POST /v1/shelves/{shelfPublicId}/approve`                   | No                                        | Yes      | No      | No       |
| `POST /v1/shelves/{shelfPublicId}/regenerate`                | No                                        | Yes      | No      | No       |
| `POST /v1/shelves/{shelfPublicId}/retry`                     | No                                        | No       | No      | Yes      |
| `GET /v1/shelves/{shelfPublicId}/versions`                   | No                                        | No       | Yes     | No       |
| `GET /v1/shelves/{shelfPublicId}/versions/{version}/tree`    | No                                        | No       | Yes     | No       |
| `GET /v1/shelves/{shelfPublicId}/versions/{version}/files/*` | No                                        | No       | Yes     | No       |

## Review mode

Default behavior:

* Dashboard uploads: review mode enabled
* API uploads: review mode disabled unless `review=true`

In `review`, you can approve with optional operations (`rename`, `delete`, `mkdir`, `write`) or trigger regeneration.

## Failed shelves

Retry a failed shelf:

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"poimandres"}}
  curl -X POST https://api.shelv.dev/v1/shelves/{shelfPublicId}/retry \
    -H "Authorization: Bearer sk_your_api_key"
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"poimandres"}}
  const res = await fetch(
    `https://api.shelv.dev/v1/shelves/${shelfPublicId}/retry`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.SHELV_API_KEY}` },
    },
  );
  const shelf = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"poimandres"}}
  import os
  import requests

  res = requests.post(
      f"https://api.shelv.dev/v1/shelves/{shelf_public_id}/retry",
      headers={"Authorization": f"Bearer {os.environ['SHELV_API_KEY']}"},
  )
  shelf = res.json()
  ```
</CodeGroup>