> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shelv.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON File Tree

> Retrieve a shelf as a flat JSON map of path to file 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

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"poimandres"}}
  curl https://api.shelv.dev/v1/shelves/{shelfPublicId}/tree \
    -H "Authorization: Bearer sk_your_api_key"
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"poimandres"}}
  const res = await fetch(
    `https://api.shelv.dev/v1/shelves/${shelfPublicId}/tree`,
    {
      headers: { Authorization: `Bearer ${process.env.SHELV_API_KEY}` },
    },
  );
  const tree = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"poimandres"}}
  import os
  import requests

  res = requests.get(
      f"https://api.shelv.dev/v1/shelves/{shelf_public_id}/tree",
      headers={"Authorization": f"Bearer {os.environ['SHELV_API_KEY']}"},
  )
  tree = res.json()
  ```
</CodeGroup>

Rules:

* Shelf status must be `ready` or `review`

Response shape:

```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
  "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)

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
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:

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"poimandres"}}
  curl https://api.shelv.dev/v1/shelves/{shelfPublicId}/files/clauses/force-majeure.md \
    -H "Authorization: Bearer sk_your_api_key"
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"poimandres"}}
  const res = await fetch(
    `https://api.shelv.dev/v1/shelves/${shelfPublicId}/files/clauses/force-majeure.md`,
    { headers: { Authorization: `Bearer ${process.env.SHELV_API_KEY}` } },
  );
  const markdown = await res.text();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"poimandres"}}
  import os
  import requests

  res = requests.get(
      f"https://api.shelv.dev/v1/shelves/{shelf_public_id}/files/clauses/force-majeure.md",
      headers={"Authorization": f"Bearer {os.environ['SHELV_API_KEY']}"},
  )
  markdown = res.text
  ```
</CodeGroup>

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