Shelves - Shelv

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:

curl -X POST https://api.shelv.dev/v1/shelves/{shelfPublicId}/retry \
  -H "Authorization: Bearer sk_your_api_key"

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();

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()