Skip to main content

​
JSON File Tree

For environments where mounting an S3 filesystem isn’t practical — like serverless functions, Vercel’s bash tool, or lightweight sandboxes — you can fetch the entire file tree as a JSON object.

​
Fetch the Tree

curl https://api.shelv.dev/api/shelves/{id}/tree \
  -H "Authorization: Bearer sk_your_api_key"
Response: 
{
  "shelfId": "a1b2c3d4-...",
  "name": "My Contract",
  "fileCount": 8,
  "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...",
    "clauses/arbitration.md": "# Arbitration\n\n...",
    "metadata.json": "{\"title\": \"Voyage Charter\", ...}"
  }
}
The files object is a flat map of path → content. Directory structure is encoded in the paths (e.g., clauses/force-majeure.md).

​
Use with AI Agents

​
Write to a Virtual Filesystem

import os

tree = shelv_client.get_tree(shelf_id)

for path, content in tree["files"].items():
    full_path = f"/tmp/shelf/{path}"
    os.makedirs(os.path.dirname(full_path), exist_ok=True)
    with open(full_path, "w") as f:
        f.write(content)

# Now the agent can use standard file tools

​
Search In-Memory

# Find all files mentioning "indemnity"
matches = {
    path: content
    for path, content in tree["files"].items()
    if "indemnity" in content.lower()
}

​
Use with Vercel AI SDK

const tree = await fetch(`https://api.shelv.dev/api/shelves/${shelfId}/tree`, {
  headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());

// Pass file contents as tool context
const relevantFiles = Object.entries(tree.files)
  .filter(([path]) => path.startsWith("clauses/"))
  .map(([path, content]) => `--- ${path} ---\n${content}`)
  .join("\n\n");

​
Fetch a Single File

If you only need one file, use the individual file endpoint: 
curl https://api.shelv.dev/api/shelves/{id}/files/clauses/force-majeure.md \
  -H "Authorization: Bearer sk_your_api_key"
This returns raw Markdown (or JSON for .json files) with the appropriate Content-Type header. More efficient than fetching the entire tree when you know which file you need.

​
When to Use Tree vs. S3 Mounting

ApproachBest for
JSON treeServerless functions, in-memory agents, quick lookups
S3 mountingLong-running sandboxes, agents that use shell tools, large documents
Single fileWhen you know exactly which file you need