# Get a file

> One file from the code tree, ready to display.

`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/files/{path}` (key permission: `buckets:read`)

Returns a file's content with a detected `language` for syntax highlighting. Text comes back as UTF-8; binary files as base64. Add `download=1` to get the raw bytes instead. Files up to 2 MB are in the code tree; bigger ones stay in their zip.

## Authorizations

- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): The Account ID that owns the key, like `CL-7K2M9QXA`. Find it in Console › Settings. A missing value answers `401 missing_account_id`; someone else's answers `401 account_mismatch`.

## Path parameters

- `bucket_id` (string, required): The bucket id (`cbk_…`).
- `path` (string, required): The file path, like `src/index.ts` (URL-encode each segment).

## Query parameters

- `ref` (string): A code ref; defaults to the current tree. With an explicit `ref` the response is cached.
- `download` (string): `1` returns the raw file bytes.

## Response

- `object` (string): `file`.
- `path` (string): The path.
- `ref` (string): The ref read.
- `size` (integer): Bytes.
- `binary` (boolean): `true` for binary files.
- `encoding` (string): `utf-8` or `base64`.
- `content` (string): The file content.
- `language` (string | null): Like `typescript`, `python`, `json`; `null` for unknown or binary.

## Example request

```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/files/PATH?ref=9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key / missing_account_id / account_mismatch` | The key or Account ID is wrong. |
| `402` | `quota_exceeded` | This month's free tokens are used up. |
| `403` | `insufficient_scope` | The key lacks the permission. |
| `404` | `not_found` | No file at that path. |
| `400` | `bad_path / bad_ref` | Invalid path or ref. |

## Example response

```json
{
  "object": "file",
  "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
  "path": "src/index.ts",
  "ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
  "size": 5121,
  "binary": false,
  "encoding": "utf-8",
  "content": "import { serve } from \"./server\";\n…",
  "language": "typescript"
}
```