Skip to main content
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 to avoid polling and trigger downstream steps when shelves become ready, review, or failed.