Skip to main content
Upload a document, wait for structuring, then point your agent at the files.

​
Prerequisites

You need a Shelv API key. Pick whichever path suits your workflow:
No browser required — ideal for AI agents and coding agents (Claude Code, Codex, OpenClaw).
# Register
curl -X POST https://api.shelv.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com", "password": "your-secure-password"}'

# Check your email for the 6-digit code, then verify
curl -X POST https://api.shelv.dev/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "code": "123456"}'
The verify response contains your API key. Save it:
export SHELV_API_KEY="sk_live_..."
See the full Authentication guide for details.
Set environment variables: 
export SHELV_API_URL="https://api.shelv.dev"
export SHELV_API_KEY="sk_your_api_key"

​
1. Upload a document

curl -X POST "$SHELV_API_URL/v1/shelves" \
  -H "Authorization: Bearer $SHELV_API_KEY" \
  -F "file=@contract.pdf" \
  -F "name=My Contract"
Optional fields:
  • template=book|legal-contract|charter-party|academic-paper
  • review=true to pause in review before finalization
Save the returned shelf public ID: 
export SHELF_PUBLIC_ID="shf_0123456789abcdef01234567"

​
2. Wait for completion

Common flow: uploading -> parsing -> structuring -> verifying -> ready If review=true, status stops at review until you call POST /v1/shelves/{shelfPublicId}/approve.

​
3. Browse the filesystem

When status is ready or review: 
curl "$SHELV_API_URL/v1/shelves/$SHELF_PUBLIC_ID/tree" \
  -H "Authorization: Bearer $SHELV_API_KEY"

​
4. Read a file

curl "$SHELV_API_URL/v1/shelves/$SHELF_PUBLIC_ID/files/clauses/force-majeure.md" \
  -H "Authorization: Bearer $SHELV_API_KEY"

​
5. Choose how your agent accesses files

  • @shelv/mcp — MCP server for MCP clients (source)
  • OpenClaw skill — upload, poll, and hydrate from OpenClaw
  • GET /v1/shelves/{shelfPublicId}/tree for full tree access
  • GET /v1/shelves/{shelfPublicId}/files/* for individual file reads
  • GET /v1/shelves/{shelfPublicId}/archive-url for snapshots
  • GET /v1/helpers/download.sh for archive pull
  • @shelv/adapters for sandbox hydration and snapshots (source)
Already set up a webhook? You can skip polling entirely — see step 2.

​
Next steps

Shelves

Understand lifecycle and status-gated endpoints.

Authentication

Lock down API key and route auth behavior.

Webhooks

Receive signed lifecycle events.

Archive Download

Pull portable snapshots for CI and offline jobs.

MCP Server

Connect Claude Code, Cursor, or any MCP client.