Skip to main content

​
Shelves

A shelf is a structured Markdown filesystem generated from an uploaded document. It’s the core resource in Shelv.

​
Lifecycle

When you upload a document, the shelf progresses through these statuses:
StatusDescription
uploadingFile received, stored in object storage
parsingPDF is being converted to raw Markdown via LlamaParse
structuringLLM is analyzing the content and creating the filesystem layout
verifyingContent integrity checks are running (no dropped or duplicated content)
reviewStructure is ready for human inspection (if review mode is enabled)
readyShelf is finalized and available for use
failedProcessing encountered an error — can be retried

​
Review Mode

When review mode is enabled, the shelf pauses at the review status instead of going directly to ready. This lets you:
  • Inspect the generated structure via the file tree
  • Apply file operations (rename, delete, mkdir, write) before finalizing
  • Regenerate the structure if it’s not satisfactory
Dashboard uploads always use review mode. API uploads skip review by default — pass review=true to enable it.

​
Approving a Shelf

When you’re satisfied with the structure, approve the shelf to transition it to ready: 
curl -X POST https://api.shelv.dev/api/shelves/{id}/approve \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"operations": []}'
You can include file operations in the operations array to modify the structure before approval: 
{
  "operations": [
    { "type": "rename", "from": "chapter-1.md", "to": "introduction.md" },
    { "type": "delete", "path": "metadata.json" },
    { "type": "write", "path": "README.md", "content": "# My Document" }
  ]
}

​
Regenerating

If the structure is unsatisfactory, trigger a regeneration to re-run the structuring step: 
curl -X POST https://api.shelv.dev/api/shelves/{id}/regenerate \
  -H "Authorization: Bearer sk_your_api_key"

​
Retrying Failed Shelves

If processing fails, you can retry from the beginning: 
curl -X POST https://api.shelv.dev/api/shelves/{id}/retry \
  -H "Authorization: Bearer sk_your_api_key"
This cleans up any partial output and re-triggers the full pipeline.

​
Output Format

A shelf’s filesystem consists of:
  • Markdown files (.md) — document content split into logical sections
  • Metadata (metadata.json) — document-level information
  • Nested directories — representing the document’s hierarchical structure
File paths follow a consistent naming convention based on the document’s headings and sections. For example, a legal contract might produce: 
definitions.md
article-01-parties.md
article-05-laytime/
  5.1-calculation.md
  5.2-exceptions.md
  5.3-demurrage.md
clauses/
  force-majeure.md
  arbitration.md