Skip to main content

​
Quickstart

This guide walks you through uploading a document, checking its status, and retrieving the structured file tree.

​
Prerequisites

  • A Shelv account — sign up at shelv.dev
  • An API key — create one in the dashboard under Settings > API Keys

​
1. Upload a Document

curl -X POST https://api.shelv.dev/api/shelves \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "file=@contract.pdf" \
  -F "name=My Contract"
Response: 
{
  "id": "a1b2c3d4-...",
  "name": "My Contract",
  "status": "uploading",
  "template": null,
  "createdAt": "2025-01-15T10:30:00.000Z",
  ...
}
The shelf starts processing immediately. Status progresses through: uploading → parsing → structuring → verifying → ready.

​
2. Check Status

Poll the shelf until it reaches ready: 
curl https://api.shelv.dev/api/shelves/a1b2c3d4-... \
  -H "Authorization: Bearer sk_your_api_key"
For production use, set up webhooks instead of polling. Shelv will notify you when processing completes.

​
3. Get the File Tree

Once the shelf is ready, fetch the complete file tree with contents: 
curl https://api.shelv.dev/api/shelves/a1b2c3d4-.../tree \
  -H "Authorization: Bearer sk_your_api_key"
Response: 
{
  "shelfId": "a1b2c3d4-...",
  "name": "My Contract",
  "fileCount": 12,
  "files": {
    "definitions.md": "# Definitions\n\n**Vessel** means...",
    "article-01-parties.md": "# Article 1 — Parties\n\n...",
    "clauses/force-majeure.md": "# Force Majeure\n\n..."
  }
}
Endpoint availability is status-based: GET /api/shelves/:id/tree and GET /api/shelves/:id/files/* work in ready and review. GET /api/shelves/:id/creds is available only in ready.

​
4. Read a Single File

You can also fetch individual files: 
curl https://api.shelv.dev/api/shelves/a1b2c3d4-.../files/clauses/force-majeure.md \
  -H "Authorization: Bearer sk_your_api_key"
This returns the raw Markdown content with the appropriate Content-Type header.

​
5. Mount via S3 (Optional)

For sandbox environments, get temporary S3 credentials and mount the filesystem directly: 
curl https://api.shelv.dev/api/shelves/a1b2c3d4-.../creds \
  -H "Authorization: Bearer sk_your_api_key"
See the Mounting via S3 guide for full setup instructions.

​
Next Steps

Templates

Use templates to guide how documents are structured.

Webhooks

Get notified when shelves are ready instead of polling.

Mounting via S3

Mount shelves as real filesystems in sandboxes.

Archive Download

Download a shelf as a .tar.gz for CI pipelines or offline use.

JSON Tree

Fetch the file tree for in-memory use.