> ## 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.

# Processing Pipeline

> User-visible processing behavior from upload to terminal shelf state.

Processing is asynchronous. You track progress through shelf status and consume results when the shelf reaches a terminal state.

## Status flow

1. `uploading`
2. `parsing`
3. `structuring`
4. `verifying`
5. terminal state: `ready`, `review`, or `failed`

## Integration guarantees

* Status is always available from `GET /v1/shelves/{id}`
* `tree` and `files` endpoints are available in `ready` and `review`
* `archive-url` is available in `ready` and `review`
* `failed` shelves can be restarted with `POST /v1/shelves/{id}/retry`

These guarantees are the stable contract to build against; your client should branch by status before calling access endpoints.

## Failure behavior

On failure, shelf status becomes `failed` and the response includes:

* `errorMessage`
* `failedAtStep`

Use these fields for alerting, retries, and user-facing status messaging.

If you request a status-gated endpoint before a shelf is eligible, the API returns a conflict response. Build callers to branch by current shelf status before requesting `tree`, `files`, or `archive-url`.

If you use automation, pair conflict handling with a short retry strategy or webhook-driven wake-up logic.

## Completion notifications

Use [webhooks](/guides/webhooks) to avoid polling and trigger downstream steps when shelves become `ready`, `review`, or `failed`.