Clatter Labs
Console

Code Buckets

List bucket events

View as Markdown

The bucket's change feed.

GETapi.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/eventsbuckets:read

Every upload, code change, deletion, backup, restore and key action in the bucket, newest first.

The response is a list (object, data, has_more, next_before); the fields above describe each event in data.

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

Query parameters

limitintegerdefault: 50

How many to return, 1 to 100.

beforestring

A created_at (or at) timestamp: return items before it, for paging.

typestring

Only this event type, or a prefix ending in a dot (backup.).

Response

200 · application/json

objectstring

Always event.

idstring

The event id (cbe_…).

typestring

What happened, like upload.completed or backup.restored. See Events for the full list.

summarystring

One line for people.

project_id / bucket_idstring

Where it happened (bucket_id is null for project events).

actorobject

Who did it: { type: "api_key", key_id, key_name }, { type: "console" } or { type: "system" }.

dataobject

Details for the type (ids, sizes, refs).

atstring

ISO 8601 timestamp.

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 bucket with that id on your account.
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/events?limit=20" \
  -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/events", params={"limit": "20"}, 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/events?limit=20", {
  method: "GET",
  headers,
});
console.log(await res.json());
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "cbe_7y2u5i8o1p4a6s9d3f0g",
      "type": "code.updated",
      "summary": "Code tree updated from storefront.zip: 1284 files, 3 kept in the archive only",
      "project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
      "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
      "actor": {
        "type": "api_key",
        "key_id": "key_7f3a…",
        "key_name": "CI"
      },
      "data": {
        "object_id": "cbo_m2n8b4v6c1x9z3l7k5j0",
        "ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
        "files": 1284,
        "skipped": 3,
        "target_path": ""
      },
      "at": "2026-10-28T14:06:52.311Z"
    }
  ],
  "has_more": false,
  "next_before": null
}