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

# Proof & Trust

> How Shelv ensures structured output quality, delivery reliability, and secure integrations.

This page is the implementation-level trust contract for teams evaluating Shelv.

## What Shelv guarantees

### 1) Deterministic access shape

Once a shelf is in `ready` (or `review`), the API exposes a stable filesystem interface:

* `GET /v1/shelves/{id}/tree`
* `GET /v1/shelves/{id}/files/{path}`
* `GET /v1/shelves/{id}/archive-url`

Build against shelf status and these endpoints as your integration boundary.

### 2) Verified structuring before availability

Shelves move through:

`uploading -> parsing -> structuring -> verifying -> ready|review|failed`

The `verifying` phase is where Shelv checks output integrity before making a shelf available.

### 3) Explicit terminal states

A shelf eventually reaches one of these terminal states:

* `ready` — usable for all read/hydration flows
* `review` — usable for read/hydration, pending approval workflows
* `failed` — contains failure metadata and is retryable

## Output integrity checks

Shelv verifies structured output before serving it:

* Content integrity validation across processing stages
* Coverage checks to prevent dropped sections
* Structural sanity checks on generated filesystem output
* Status-gated endpoint availability (no premature reads)

If verification fails, shelf status is set to `failed` and includes failure metadata.

## Reliability patterns for production

### Prefer event-driven completion

Use [webhooks](/guides/webhooks) instead of aggressive polling.

Recommended flow:

1. Upload document (`POST /v1/shelves`)
2. Store shelf id
3. Wait for `shelf.ready` / `shelf.review` / `shelf.failed`
4. Fetch `tree` or hydrate via `archive-url`

### Implement idempotency and retries

Webhook delivery is at-least-once. Consumers should:

* dedupe by `webhook-id`
* verify signature and timestamp freshness
* safely retry downstream operations

### Handle conflict responses as a state signal

If a status-gated endpoint returns conflict, branch on current shelf status and retry only when eligible.

## Failure behavior you can rely on

When a shelf fails:

* status becomes `failed`
* metadata includes failure step and message
* `POST /v1/shelves/{id}/retry` can re-run processing

This enables robust automation and user-facing error reporting.

## Security posture (integration-facing)

### API authentication

* API keys are required for API access (`Bearer sk_...`)
* Dashboard and API auth are separated by use case

### Webhook safety

Shelv webhook delivery includes:

* signed payloads (`webhook-signature`)
* timestamping (`webhook-timestamp`)
* idempotency key (`webhook-id`)

Production endpoint constraints include HTTPS and network safety validation. See [Webhooks](/guides/webhooks) for full details.

### Principle of least privilege

Scope keys to your environment and rotate on a schedule. Treat webhook secrets and API keys as production credentials.

## Integration trust checklist

Before production rollout:

* [ ] Branch by shelf status before file access
* [ ] Use webhook-driven completion
* [ ] Verify webhook signatures and timestamps
* [ ] Deduplicate by `webhook-id`
* [ ] Implement retry paths for `failed` shelves
* [ ] Add operational alerts for repeated failures

## What to measure internally

For your own proof baseline, track:

* time from upload to `ready`
* success vs failed shelf rate
* retry success rate
* time from `ready` to first successful agent read

These metrics make adoption, reliability, and ROI visible across teams.