Clatter Labs
Console

Code Buckets

Start an upload

View as Markdown

Open a resumable upload for a zip or an asset.

POSTapi.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/uploadsbuckets:write

Reserves space in the bucket and returns the upload with its chunk layout. Send the file as chunk_count chunks of chunk_size bytes (the last one is shorter) with Upload a chunk, then complete the upload.

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_…).

Body

application/json

namestringrequired

The file name, like storefront.zip (no slashes, up to 255 characters).

sizeintegerrequired

The exact file size in bytes.

kindstring

archive or asset. Defaults to archive for .zip names, asset otherwise.

target_pathstring

Archives only: unpack into this folder (like packages/api) and keep the rest of the tree. Omit to replace the whole tree.

content_typestring

MIME type returned on download.

visibilitystring

inherit (default: follow the bucket), private or public. Pass public to get a public link as soon as the upload completes.

Response

201 · application/json

objectstring

upload while it's being uploaded, then object.

idstring

The upload id, which is also the stored object's id (cbo_…).

bucket_idstring

The bucket it belongs to.

kindstring

archive (a zip of code) or asset (any other file).

namestring

The file name.

target_pathstring

Archives only: the folder the zip is unpacked into ("" = the whole tree).

sizeinteger

Size in bytes.

chunk_sizeinteger

Bytes per chunk: 16,777,216 (16 MiB).

chunk_countinteger

How many chunks the file has.

statusstring

uploading, processing (building the preview), ready or failed.

received_chunksinteger[]

While uploading: the chunk indexes already stored. Upload only the missing ones to resume.

previewobject

Archives 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.

visibilitystring

The file's own setting: inherit (default: follow the bucket), private or public.

effective_visibilitystring

What applies now: private or public (the file's setting, or the bucket's when it's inherit).

public_urlstring | null

The 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_asstring

image (public link on img.cdn.clatterlabs.xyz, cached for a year) or file (files.cdn-buckets.clatterlabs.xyz).

encryptedboolean

Always true.

created_at / completed_atstring

ISO 8601 timestamps.

Errors

StatusCodeWhen
400bad_requestA field is missing or invalid.
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 bucket with that id on your account.
413bucket_fullThe upload would take the bucket past 10 GB (counting unfinished uploads).
503storage_unavailableTry again.
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/uploads" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "storefront.zip",
    "size": 131204115
  }'
import os
import requests

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

r = requests.post(
    "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/uploads",
    headers=headers,
    json={
        "name": "storefront.zip",
        "size": 131204115
    },
)
print(r.json())
const headers = {
  Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
  "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
  "Content-Type": "application/json",
};

const res = await fetch("https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/uploads", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "name": "storefront.zip",
    "size": 131204115
  }),
});
console.log(await res.json());
{
  "object": "upload",
  "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": "uploading",
  "received_chunks": [],
  "preview": {
    "status": "pending"
  },
  "visibility": "inherit",
  "effective_visibility": "private",
  "public_url": null,
  "served_as": "file",
  "encrypted": true,
  "created_at": "2026-10-28T14:05:11.482Z",
  "completed_at": null
}