Code Buckets
Get an object
One stored zip or asset.
Returns the object, including its preview result for zips.
Authorizations
AuthorizationstringrequiredYour API key as a bearer token: Bearer clsk_.... Create keys in the Console with the Code Buckets permissions you need.
X-Clatter-AccountstringrequiredThe 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_idstringrequiredThe bucket id (cbk_…).
object_idstringrequiredThe object id (cbo_…).
Response
200 · application/json
objectstringupload while it's being uploaded, then object.
idstringThe upload id, which is also the stored object's id (cbo_…).
bucket_idstringThe bucket it belongs to.
kindstringarchive (a zip of code) or asset (any other file).
namestringThe file name.
target_pathstringArchives only: the folder the zip is unpacked into ("" = the whole tree).
sizeintegerSize in bytes.
chunk_sizeintegerBytes per chunk: 16,777,216 (16 MiB).
chunk_countintegerHow many chunks the file has.
statusstringuploading, processing (building the preview), ready or failed.
received_chunksinteger[]While uploading: the chunk indexes already stored. Upload only the missing ones to resume.
previewobjectArchives only: { status, files, skipped, skipped_examples, stripped_folder, ms }. status is pending, extracting, ready, partial, failed or off; ms is how long building the preview took, in milliseconds.
visibilitystringThe file's own setting: inherit (default: follow the bucket), private or public.
effective_visibilitystringWhat applies now: private or public (the file's setting, or the bucket's when it's inherit).
public_urlstring | nullThe file's public link while it's public and stored, null otherwise. Images (image/*) get https://img.cdn.clatterlabs.xyz/<id>; everything else https://files.cdn-buckets.clatterlabs.xyz/<object_id>/<name>. See Public files.
served_asstringimage (public link on img.cdn.clatterlabs.xyz, cached for a year) or file (files.cdn-buckets.clatterlabs.xyz).
encryptedbooleanAlways true.
created_at / completed_atstringISO 8601 timestamps.
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 object with that id on your account. |
409 | not_ready | The upload isn't complete yet. |
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/objects/OBJECT_ID" \
-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/objects/OBJECT_ID", 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/objects/OBJECT_ID", {
method: "GET",
headers,
});
console.log(await res.json());{
"object": "object",
"id": "cbo_m2n8b4v6c1x9z3l7k5j0",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"kind": "archive",
"name": "storefront.zip",
"target_path": "",
"content_type": "application/zip",
"size": 131204115,
"chunk_size": 16777216,
"chunk_count": 8,
"status": "ready",
"preview": {
"status": "partial",
"files": 1284,
"skipped": 3,
"skipped_examples": [
{
"path": "assets/hero.mp4",
"reason": "large file (kept in the archive)"
}
],
"stripped_folder": "storefront-main",
"ms": 4180
},
"visibility": "inherit",
"effective_visibility": "private",
"public_url": null,
"served_as": "file",
"encrypted": true,
"created_at": "2026-10-28T14:05:11.482Z",
"completed_at": "2026-10-28T14:06:40.019Z"
}