Clatter Labs
Console

Code Buckets

Set file visibility

View as Markdown

Make one stored file public or private.

PATCHapi.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}/visibilitybuckets:write

Sets a stored zip or asset to public, private, or inherit (follow the bucket, the default). A public file is served, decrypted, at its public_url (images on https://img.cdn.clatterlabs.xyz/<id>, other files on https://files.cdn-buckets.clatterlabs.xyz) to anyone with the link; switching it back to private blocks the link on the next request. Recorded as an object.visibility_changed event. Counts as 1 token like any request. Making an image private retires its image id for good; it gets a new one if it's made public again.

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

object_idstringrequired

The object id (cbo_…) of a stored zip or asset.

Body

application/json

visibilitystringrequired

public, private or inherit.

Response

200 · 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_requestvisibility isn't public, private or inherit.
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 or object with that id on your account.
409not_readyThe upload isn't complete yet.
curl -X PATCH "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/objects/OBJECT_ID/visibility" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "public"
  }'
import os
import requests

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

r = requests.patch(
    "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/objects/OBJECT_ID/visibility",
    headers=headers,
    json={
        "visibility": "public"
    },
)
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/objects/OBJECT_ID/visibility", {
  method: "PATCH",
  headers,
  body: JSON.stringify({
    "visibility": "public"
  }),
});
console.log(await res.json());
{
  "object": "object",
  "id": "cbo_x4p8t2w6r1k9m3q7n5d0",
  "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
  "kind": "asset",
  "name": "hero.png",
  "content_type": "image/png",
  "size": 482133,
  "chunk_size": 16777216,
  "chunk_count": 1,
  "status": "ready",
  "visibility": "public",
  "effective_visibility": "public",
  "public_url": "https://img.cdn.clatterlabs.xyz/V1StGXR8Z5jdHi6BmyT2kq",
  "served_as": "image",
  "encrypted": true,
  "created_at": "2026-10-28T14:05:11.482Z",
  "completed_at": "2026-10-28T14:06:40.019Z"
}