Skip to main content
Use the tree endpoint when you need full content in memory without archive download. It is a good fit for short-lived workers, serverless handlers, and indexing pipelines.

​
Fetch the tree

curl https://api.shelv.dev/v1/shelves/{shelfPublicId}/tree \
  -H "Authorization: Bearer sk_your_api_key"
Rules:
  • Shelf status must be ready or review
Response shape: 
{
  "shelfPublicId": "shf_0123456789abcdef01234567",
  "name": "My Contract",
  "fileCount": 8,
  "files": {
    "README.md": "# My Contract\\n...",
    "clauses/force-majeure.md": "# Force Majeure\\n...",
    "metadata.json": "{\"title\":\"Voyage Charter\"}"
  }
}
The files object is a flat path -> content map. fileCount reports the number of entries returned in the map. Because directory hierarchy is encoded in keys, preserve paths exactly if you rematerialize files locally.

​
Materialize locally (optional)

mkdir -p /tmp/shelf
Then write each entry to disk in your runtime if needed. Use this step only when your toolchain requires local file I/O; otherwise process content directly from memory.

​
Prefer single-file reads when possible

If you already know the path, use: 
curl https://api.shelv.dev/v1/shelves/{shelfPublicId}/files/clauses/force-majeure.md \
  -H "Authorization: Bearer sk_your_api_key"
This avoids transferring the full tree for large shelves. When building agents, start with targeted single-file reads and use full-tree fetches for indexing or bulk preprocessing.

​
Tree vs alternatives

  • JSON tree: full in-memory access
  • Sandbox adapters: filesystem hydration plus snapshots
  • Single file endpoint: narrow, efficient retrieval