Skip to main content
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 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 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.