# Preview

> Browse a bucket's code as a file tree, with syntax highlighting, in the Console or over the API.

When a zip finishes uploading to a bucket with **preview** on, Code Buckets unpacks it into the bucket's code tree. The Console's **Files** tab shows that tree with a search box and a highlighted viewer; the API gives you the same tree and files.

## What gets unpacked

- If every file in the zip sits inside one top folder (like `storefront-main/`, the usual shape of downloaded zips), that folder is dropped so your files start at the root. The object's `preview.stripped_folder` says which.
- Files up to **2 MB** each go into the tree, up to about 96 MB and 20,000 files per zip. Bigger files, and anything past those limits, stay safely in the stored zip; `preview.skipped` counts them and `preview.skipped_examples` names some.
- Paths that try to leave the tree (`../`), `.git/`, `__MACOSX/` and `.DS_Store` are skipped. Password-protected zip entries can't be previewed.

The object's `preview.status` ends as `ready`, `partial` (some files kept in the zip only) or `failed` (the zip couldn't be read; it's still stored).

## Reading the tree

```bash
curl "$CB/v1/buckets/BUCKET_ID/tree" \
  -H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

```json
{
  "object": "tree",
  "ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
  "files": [
    { "path": "README.md", "type": "file", "size": 1840 },
    { "path": "src", "type": "dir" },
    { "path": "src/index.ts", "type": "file", "size": 5121 }
  ],
  "truncated": false
}
```

## Reading a file

```bash
curl "$CB/v1/buckets/BUCKET_ID/files/src/index.ts?ref=9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0" \
  -H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

The response has `content` (UTF-8 text, or base64 for binary files) and a `language` (`typescript`, `python`, `json`, …) you can hand to a highlighter. Add `download=1` for the raw bytes.

<Tip>
Pass `?ref=` whenever you can. Responses for an explicit ref never change, so they're cached at the edge and come back in milliseconds.
</Tip>

## Turning preview off

Set `"preview": false` when you create or [update](/api-reference/code-buckets/buckets/update) a bucket to keep its code only in encrypted zips. New zips are then stored without being unpacked (`preview.status: "off"`); download them to read them.