# Code Buckets API

> Projects, buckets, chunked uploads, code preview, events and backups over HTTPS.

## Base URL

```text
https://api.codebuckets.clatterlabs.xyz
```

All requests use HTTPS. Bodies are JSON, except chunk uploads and downloads (raw bytes). `GET /` describes the service without a key.

## Authentication

Send your API key and your Account ID on every request. See [Authentication](/api-reference/code-buckets/authentication).

```http
Authorization: Bearer clsk_...
X-Clatter-Account: CL-XXXXXXXX
```

## Endpoints

| Method | Path | Permission | |
| --- | --- | --- | --- |
| `GET` | `/v1/projects` | `buckets:read` | [List projects](/api-reference/code-buckets/projects/list) |
| `POST` | `/v1/projects` | `buckets:write` | [Create a project](/api-reference/code-buckets/projects/create) |
| `GET` | `/v1/projects/{project_id}` | `buckets:read` | [Get a project](/api-reference/code-buckets/projects/get) |
| `PATCH` | `/v1/projects/{project_id}` | `buckets:write` | [Update a project](/api-reference/code-buckets/projects/update) |
| `DELETE` | `/v1/projects/{project_id}` | `buckets:write` | [Delete a project](/api-reference/code-buckets/projects/delete) |
| `GET` | `/v1/projects/{project_id}/events` | `buckets:read` | [List project events](/api-reference/code-buckets/projects/events) |
| `GET` | `/v1/projects/{project_id}/buckets` | `buckets:read` | [List buckets](/api-reference/code-buckets/buckets/list) |
| `POST` | `/v1/projects/{project_id}/buckets` | `buckets:write` | [Create a bucket](/api-reference/code-buckets/buckets/create) |
| `GET` | `/v1/buckets/{bucket_id}` | `buckets:read` | [Get a bucket](/api-reference/code-buckets/buckets/get) |
| `PATCH` | `/v1/buckets/{bucket_id}` | `buckets:write` | [Update a bucket](/api-reference/code-buckets/buckets/update) |
| `DELETE` | `/v1/buckets/{bucket_id}` | `buckets:write` | [Delete a bucket](/api-reference/code-buckets/buckets/delete) |
| `GET` | `/v1/buckets/{bucket_id}/events` | `buckets:read` | [List bucket events](/api-reference/code-buckets/buckets/events) |
| `POST` | `/v1/buckets/{bucket_id}/uploads` | `buckets:write` | [Start an upload](/api-reference/code-buckets/uploads/create) |
| `PUT` | `/v1/uploads/{upload_id}/chunks/{index}` | `buckets:write` | [Upload a chunk](/api-reference/code-buckets/uploads/chunk) |
| `GET` | `/v1/uploads/{upload_id}` | `buckets:read` | [Get an upload](/api-reference/code-buckets/uploads/get) |
| `POST` | `/v1/uploads/{upload_id}/complete` | `buckets:write` | [Complete an upload](/api-reference/code-buckets/uploads/complete) |
| `POST` | `/v1/uploads/{upload_id}/abort` | `buckets:write` | [Abort an upload](/api-reference/code-buckets/uploads/abort) |
| `GET` | `/v1/buckets/{bucket_id}/objects` | `buckets:read` | [List objects](/api-reference/code-buckets/objects/list) |
| `GET` | `/v1/buckets/{bucket_id}/objects/{object_id}` | `buckets:read` | [Get an object](/api-reference/code-buckets/objects/get) |
| `GET` | `/v1/buckets/{bucket_id}/objects/{object_id}/content` | `buckets:read` | [Download an object](/api-reference/code-buckets/objects/download) |
| `GET` | `/v1/buckets/{bucket_id}/objects/{object_id}/chunks/{index}` | `buckets:read` | [Download a chunk](/api-reference/code-buckets/objects/chunk) |
| `DELETE` | `/v1/buckets/{bucket_id}/objects/{object_id}` | `buckets:write` | [Delete an object](/api-reference/code-buckets/objects/delete) |
| `GET` | `/v1/buckets/{bucket_id}/tree` | `buckets:read` | [Get the code tree](/api-reference/code-buckets/preview/tree) |
| `GET` | `/v1/buckets/{bucket_id}/files/{path}` | `buckets:read` | [Get a file](/api-reference/code-buckets/preview/file) |
| `GET` | `/v1/buckets/{bucket_id}/backups` | `buckets:read` | [List backups](/api-reference/code-buckets/backups/list) |
| `POST` | `/v1/buckets/{bucket_id}/backups` | `backups:write` | [Create a backup](/api-reference/code-buckets/backups/create) |
| `GET` | `/v1/backups/{backup_id}` | `buckets:read` | [Get a backup](/api-reference/code-buckets/backups/get) |
| `POST` | `/v1/backups/{backup_id}/restore` | `backups:write` | [Restore a backup](/api-reference/code-buckets/backups/restore) |
| `DELETE` | `/v1/backups/{backup_id}` | `backups:write` | [Delete a backup](/api-reference/code-buckets/backups/delete) |
| `GET` | `/v1/usage` | `buckets:read` | [Get usage](/api-reference/code-buckets/usage) |

## Response headers

| Header | Meaning |
| --- | --- |
| `X-Codebuckets-Tokens` | Tokens this request used ([Pricing](/code-buckets/pricing)) |
| `X-RateLimit-Limit` | The key's per-minute limit |
| `X-Request-Id` | Quote it when you contact support |
| `X-Content-SHA256` | On chunk downloads: the chunk's SHA-256 |

## Objects and ids

Every JSON object has an `object` field (`project`, `bucket`, `upload`, `object`, `event`, `backup`, `tree`, `file`, `list`). Lists are `{ "object": "list", "data": [...], "has_more": bool }`, newest first; page with `before`.

## Versioning

The API version is a date, returned by `GET /` as `version` (currently `2026-10-28`). Breaking changes get a new version and a changelog entry.

<CardGroup cols={2}>
<Card title="Quickstart" icon="rocket" href="/code-buckets/quickstart">First upload in five minutes.</Card>
<Card title="Errors" icon="circle-alert" href="/api-reference/code-buckets/errors">Codes and what to do.</Card>
</CardGroup>