Clatter Labs
Console

Code Buckets

Get a file

View as Markdown

One file from the code tree, ready to display.

GETapi.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/files/{path}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

Authorizationstringrequired

Your API key as a bearer token: Bearer clsk_.... Create keys in the Console with the Code Buckets permissions you need.

X-Clatter-Accountstringrequired

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_idstringrequired

The bucket id (cbk_…).

pathstringrequired

The file path, like src/index.ts (URL-encode each segment).

Query parameters

refstring

A code ref; defaults to the current tree. With an explicit ref the response is cached.

downloadstring

1 returns the raw file bytes.

Response

200 · application/json

objectstring

file.

pathstring

The path.

refstring

The ref read.

sizeinteger

Bytes.

binaryboolean

true for binary files.

encodingstring

utf-8 or base64.

contentstring

The file content.

languagestring | null

Like typescript, python, json; null for unknown or binary.

Errors

StatusCodeWhen
401invalid_api_key / missing_account_id / account_mismatchThe key or Account ID is wrong.
402quota_exceededThis month's free tokens are used up.
403insufficient_scopeThe key lacks the permission.
404not_foundNo file at that path.
400bad_path / bad_refInvalid path or ref.
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"
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}",
    "X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"],
}

r = requests.get("https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/files/PATH", params={"ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0"}, headers=headers)
print(r.json())
const headers = {
  Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
  "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
};

const res = await fetch("https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/files/PATH?ref=9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0", {
  method: "GET",
  headers,
});
console.log(await res.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"
}