# Clatter Labs Docs (full text)
> Guides and API reference for Clatter Labs developer products: the Cosmos Agent API (an AI agent API for coding), Line CLI, the Model API, Code Buckets and the SuperCosmos and Line Code models.
Every page of https://developers.clatterlabs.com in navigation order, as Markdown. Index: https://developers.clatterlabs.com/llms.txt
---
Source: https://developers.clatterlabs.com/
# Introduction
> Build with the Cosmos Agent API, an AI agent API for coding, and code in your terminal with Line CLI.
Clatter Labs builds developer tools around one idea: an agent should do real work, on a real computer, and hand you back something you can check. These docs cover everything you can build on.
Create a key and start your first Cosmos Agent run in about five minutes.
Every Agent API endpoint, with parameters, examples and a live playground.
The fast terminal coding agent. Install it with one command.
Create a key in the Console and send it with your Account ID.
## What you can build
An AI coding agent you call over HTTPS. Each run gets its own cloud computer: terminal, files, browser, database and hosting.
Three tiers, Flash, Max and Heavy, behind every Clatter Labs product. Pick one per run, or let Cosmos route.
Every error code, rate limit and run limit, and what to do about each.
API keys, usage, logs, your plan and your credits.
## How the pieces fit
1. You sign in to the **Console** with your Clatter Labs account. Your **Account ID** (`CL-…`) is shown there.
2. In the Console you create API keys and watch usage against your **plan** and **credits**.
3. The **Agent API** starts **Cosmos Agent** runs. Each run thinks with **SuperCosmos** and works on its own cloud computer.
4. **Line CLI** brings the same models to your terminal and can hand bigger jobs to Cosmos in the cloud.
Every account has a plan (Free included) covering Line CLI, Cosmos Agent and Code Buckets, and new accounts start with **$5 of free credit** for the Model API and Agent API, which are pay as you go on every plan. See [Plans and credits](/billing/credits).
## Other Clatter Labs services
A full development environment in the browser.Clatter Labs' official short and dynamic links.Live health of every Clatter Labs service.Answers and guides for every Clatter Labs product.
---
Source: https://developers.clatterlabs.com/quickstart
# Quickstart
> Create an API key and start your first Cosmos Agent run in about five minutes.
This guide takes you from nothing to a finished agent run: Cosmos writes a small program on its cloud computer, runs it, and tells you the result.
## Before you start
You need a **Clatter Labs account**. If you don't have one, create it at [accounts.clatterlabs.com](https://accounts.clatterlabs.com). The Agent API works on every plan, Free included; runs are paid from credits ([Plans and credits](/billing/credits)).
Sign in to the [Console](https://console.clatterlabs.com) with your Clatter Labs account. Your **Account ID** looks like `CL-7K2M9QXA` and is shown with a copy button on the Home page and in **Settings**. Every API request sends it next to your key.
Go to **API keys** › **Create key**. Give it a name, keep the `runs:write` and `runs:read` permissions, and pick a rate limit (30 requests per minute is the default).
The key starts with `clsk_` and is **shown only once**. Copy it now; Clatter Labs stores only a hash of it.
```bash
export CLATTER_API_KEY="clsk_..." # Console › API keys
export CLATTER_ACCOUNT_ID="CL-XXXXXXXX" # Console › Settings
```
Send Cosmos your instructions. The API answers `201` right away with the run.
```bash cURL
curl https://api.agent.clatterlabs.xyz/v1/runs \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"input": "Write hello.py that prints the date, run it, and tell me the output.",
"title": "Hello from the API"
}'
```
```python Python
import os, requests
headers = {
"Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}",
"X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"],
}
run = requests.post(
"https://api.agent.clatterlabs.xyz/v1/runs",
headers=headers,
json={"input": "Write hello.py that prints the date, run it, and tell me the output."},
).json()
print(run["id"], run["status"])
```
```javascript JavaScript
const headers = {
Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
"X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
"Content-Type": "application/json",
};
const run = await fetch("https://api.agent.clatterlabs.xyz/v1/runs", {
method: "POST",
headers,
body: JSON.stringify({ input: "Write hello.py that prints the date, run it, and tell me the output." }),
}).then((r) => r.json());
console.log(run.id, run.status);
```
Stream the run's events. You'll see a `status` event, one `step` per message or tool call, and a final `done` event with the answer.
```bash
curl -N https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/events \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
Fetch the run any time for its output, the files it saved and its token usage.
```bash
curl "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID?include=files" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
Every API reference page has a **Try it** button that sends real requests from your browser, so you can explore without writing code.
## Next steps
Write good instructions, choose a tier, and read results.Follow runs live and reconnect without losing steps.When to use Flash, Max or Heavy.Every error code and what to do about it.
---
Source: https://developers.clatterlabs.com/concepts
# Core concepts
> The few ideas behind the Cosmos Agent API and Line CLI, explained once.
## Account ID
You sign in to the [Console](https://console.clatterlabs.com) with your Clatter Labs account. Each account has a permanent **Account ID**, like `CL-7K2M9QXA`, shown with a copy button on the Console's Home and Settings pages. The Agent API asks for it in the `X-Clatter-Account` header next to your key, so that a leaked key alone is not enough to act on your account.
## Cosmos Agent and runs
**Cosmos Agent** is an AI coding agent you call over an API. You describe a task; Cosmos plans, writes and runs code, browses, and saves files until it's done. One task is a **run**. A run can split work across parallel **sub-agents** and takes up to 150 steps.
## The cloud computer
Every account has its own **cloud computer** that runs work for it: a Linux terminal and files, a Chromium browser, a database and storage, hosting at `.clatterai.com`, and Cloud Repos for code. Runs use it; you never have to set it up.
## SuperCosmos tiers
Cosmos and Line CLI think with **SuperCosmos by Clatter Labs**, which comes in three tiers:
| Tier | Best for | Input / 1M tokens | Output / 1M tokens |
| --- | --- | --- | --- |
| Flash | Quick edits, answers, everyday steps | $1.60 | $3.40 |
| Max | Planning, debugging, multi-file changes | $1.80 | $3.80 |
| Heavy | Hard bugs, long builds, deep reasoning | $2.00 | $4.40 |
**Long-context input above 262K tokens: 1.5×** (SuperCosmos): a request whose prompt is over 262K tokens bills its whole input at 1.5× the rate above.
`auto` lets Cosmos pick. See [SuperCosmos models](/models/overview).
## Credits
App usage (Line CLI, Cosmos Agent, Cosmos Agent on Telegram) is covered by your **plan** (usage windows and a weekly limit on paid plans, a monthly allowance on Free); API usage (Model API, Agent API) is paid from **one credit balance per Account ID**, in US dollars. New accounts get $5 of free credit ([Plans and credits](/billing/credits)). Tokens are billed at the tier each call actually ran on; computer time, tool actions, browser time and storage writes have their own small rates. When the balance runs out, metered calls answer `402 out_of_credits`. See [Credits and billing](/billing/credits).
## API keys and permissions
Agent API keys (`clsk_…`) are made in the Console. Each key has **permissions** and its own **rate limit**:
| Permission | Allows |
| --- | --- |
| `runs:write` | Create and cancel runs |
| `runs:read` | Read runs, their events and results |
| `account:read` | Read your credit balance and usage |
---
Source: https://developers.clatterlabs.com/agent/overview
# Cosmos Agent
> An AI coding agent you call over HTTPS. Describe a task; Cosmos does the work on its own cloud computer and returns the result.
Cosmos Agent is Clatter Labs' AI agent for coding, available as an API. You send instructions in plain language. Cosmos plans the work, writes and runs code, uses a browser, keeps files, and reports back with an answer and any files it produced.
Create a key and run your first task.Create, stream, read and cancel runs.
## What a run can do
Each run works on your account's own cloud computer, with these tools:
| Tool | What Cosmos uses it for |
| --- | --- |
| Terminal and files | Install packages, run builds and tests, read and edit code |
| Browser | Open sites, click and type, check what a page really shows |
| Web search and fetch | Look up docs and references |
| Cloud Repos | Keep code in a repository, with history |
| Hosting | Deploy sites and APIs to `.clatterai.com`, with DNS, a SQL database and key-value storage |
| Database and storage | Store data and assets, install skills |
| Sub-agents | Split a big job into parallel pieces |
| Memory | Remember what it learned for later runs |
| Connected apps | Use the connectors and MCP servers on your account |
| Outputs | Save files you get back with the run |
## The run lifecycle
```text
queued ─▶ running ─▶ completed
├─▶ failed (error.code: run_failed | out_of_credits)
└─▶ cancelled (POST /v1/runs/{id}/cancel)
```
1. **Create** a run with `POST /v1/runs`. You get the run back immediately with status `running`.
2. **Follow** it with the event stream (`GET /v1/runs/{id}/events`) or poll `GET /v1/runs/{id}`.
3. **Read** the result: `output` is Cosmos's final answer; `files` lists what it saved.
Runs keep going if you disconnect. A long task continues in segments past any single request's time limit, up to 150 steps.
## Base URL and authentication
```text
https://api.agent.clatterlabs.xyz
```
Every request sends two headers: your key as a bearer token and your Account ID.
```http
Authorization: Bearer clsk_...
X-Clatter-Account: CL-XXXXXXXX
```
See [Authentication](/api-reference/authentication) for details.
The Agent API is **generally available** on **every plan, Free included**. Runs are pay as you go from your [credits](/billing/credits) (plans don't cover API calls); see [Rates](/billing/rates).
---
Source: https://developers.clatterlabs.com/agent/first-run
# Your first real run
> Write instructions Cosmos can act on, pick a tier, attach your own metadata, and read the result.
## Write instructions like a ticket
Cosmos does best with the same things a teammate would need: the goal, the constraints, and how to know it's done.
```text
Create a small Express API in a folder named todo-api with GET/POST /todos
backed by SQLite. Add tests with node:test and run them.
Done means: all tests pass. Reply with the test output and how to start the server.
```
- **Say what "done" looks like.** "Run the tests and show me the output" beats "make sure it works".
- **Name files and folders** you care about.
- **Put limits in the instructions**: "don't add dependencies", "keep it under 100 lines".
- `input` can be up to **20,000 characters**, so paste the spec, error log or snippet it needs.
## Create the run
```bash cURL
curl https://api.agent.clatterlabs.xyz/v1/runs \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"input": "Create a small Express API ... Reply with the test output.",
"title": "todo-api",
"tier": "max",
"metadata": { "ticket": "OPS-112" }
}'
```
```python Python
run = requests.post(
"https://api.agent.clatterlabs.xyz/v1/runs",
headers=headers,
json={
"input": "Create a small Express API ... Reply with the test output.",
"title": "todo-api",
"tier": "max",
"metadata": {"ticket": "OPS-112"},
},
).json()
```
```javascript JavaScript
const run = await fetch("https://api.agent.clatterlabs.xyz/v1/runs", {
method: "POST",
headers,
body: JSON.stringify({
input: "Create a small Express API ... Reply with the test output.",
title: "todo-api",
tier: "max",
metadata: { ticket: "OPS-112" },
}),
}).then((r) => r.json());
```
| Field | Notes |
| --- | --- |
| `input` | Required. Up to 20,000 characters. |
| `title` | Optional, up to 80 characters. Defaults to the first line of `input`. |
| `tier` | `auto` (default), `flash`, `max` or `heavy`. See [Choose a tier](/agent/tiers). |
| `metadata` | Optional object up to 2 KB, returned as-is. Use it to link runs to your own records. |
## Wait for it
Pick whichever fits your code:
Open the [event stream](/agent/streaming) and read events until `done`. You see each step as it happens.
Call `GET /v1/runs/{id}` every few seconds until `status` is `completed`, `failed` or `cancelled`. Keep the interval at 2 seconds or more so you stay inside your key's rate limit.
```python
import time
while True:
run = requests.get(f"{BASE}/v1/runs/{run_id}", headers=headers).json()
if run["status"] in ("completed", "failed", "cancelled"):
break
time.sleep(3)
print(run["output"])
```
## Read the result
A finished run looks like this:
```json
{
"id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
"object": "run",
"status": "completed",
"output": "All 6 tests pass. Start the server with: cd todo-api && npm start",
"files": [{ "name": "test-output.txt", "bytes": 412 }],
"steps": 23,
"tier": "max",
"usage": { "tokens": 96210 },
"metadata": { "ticket": "OPS-112" }
}
```
Add `?include=files` to get each file's `content`. See [Files and outputs](/agent/files-and-outputs).
---
Source: https://developers.clatterlabs.com/agent/streaming
# Streaming events
> Follow a run live with server-sent events, and reconnect without missing or repeating steps.
`GET /v1/runs/{id}/events` returns a `text/event-stream`. Any SSE client works, or read the response body line by line.
## Event types
| Event | Data | When |
| --- | --- | --- |
| `status` | `{ "status": "running" }` | The run's status changed |
| `step` | A step object | Cosmos wrote a message or used a tool |
| `done` | The final run | The run finished (completed, failed or cancelled) |
| `timeout` | `{ "message", "after" }` | The connection reached 10 minutes; the run continues |
| `error` | `{ "code", "message" }` | The stream had to stop, for example the key was revoked |
A `step` is either a message or a tool call:
```json
{ "index": 0, "type": "message", "text": "I'll scaffold the project first." }
{ "index": 1, "type": "tool", "name": "computer_terminal", "ok": true,
"args": "{\"cmd\":\"npm init -y\"}", "output": "Wrote to package.json" }
```
`text` is capped at 4,000 characters, `args` at 400 and `output` at 600. The full run is always available from `GET /v1/runs/{id}`.
## Reconnecting
One stream connection lasts up to **10 minutes**. Count the `step` events you've received and reconnect with `?after=` that number; the stream continues from the next step.
```javascript JavaScript
async function follow(runId) {
let after = 0;
for (;;) {
const res = await fetch(`${BASE}/v1/runs/${runId}/events?after=${after}`, { headers });
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
let buf = "", done = false;
for (;;) {
const { value, done: end } = await reader.read();
if (end) break;
buf += value;
let i;
while ((i = buf.indexOf("\n\n")) >= 0) {
const chunk = buf.slice(0, i); buf = buf.slice(i + 2);
const event = /^event: (.*)$/m.exec(chunk)?.[1];
const data = JSON.parse(/^data: (.*)$/m.exec(chunk)?.[1] ?? "null");
if (event === "step") { after = data.index + 1; console.log(data); }
if (event === "done") { done = true; return data; }
}
}
if (done) break; // otherwise: timeout or dropped connection, reconnect
}
}
```
```python Python
import json, requests
def follow(run_id):
after = 0
while True:
with requests.get(f"{BASE}/v1/runs/{run_id}/events",
params={"after": after}, headers=headers, stream=True) as r:
event = None
for line in r.iter_lines(decode_unicode=True):
if line.startswith("event: "):
event = line[7:]
elif line.startswith("data: "):
data = json.loads(line[6:])
if event == "step":
after = data["index"] + 1
print(data)
elif event == "done":
return data
# timeout or dropped connection: loop and reconnect with ?after=
```
The stream re-checks your key every few minutes. If the key is revoked while you're connected you get an `error` event and the stream ends.
---
Source: https://developers.clatterlabs.com/agent/files-and-outputs
# Files and outputs
> Get files back from a run, and keep work on the cloud computer between runs.
## Outputs
When Cosmos saves a file as an **output**, it appears in the run's `files` array:
```json
"files": [
{ "name": "report.md", "bytes": 2048 },
{ "name": "hello.py", "bytes": 61 }
]
```
Ask for the contents with `?include=files`:
```bash
curl "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID?include=files" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
Each file then also has `content`. To make sure you get a file back, say so in the instructions: *"Save the final script as an output named sync.py."*
## Work that stays on the computer
Runs work on your account's cloud computer, so code and data can outlive a run:
- **Cloud Repos** keep code with history. Ask Cosmos to "commit the project to a Cloud Repo named todo-api" and later runs can continue from it.
- **Hosting** deploys sites and APIs to `.clatterai.com`.
- **Database and storage** keep data and assets.
Treat outputs as untrusted until you've reviewed them, like any code from a pull request. Don't paste secrets into `input`; connect services to your account instead.
## Storage costs
Writes to the cloud computer and run results are billed at **$0.10 per GB written**. See [Rates](/billing/rates).
---
Source: https://developers.clatterlabs.com/agent/tiers
# Choose a tier
> When to run on Flash, Max or Heavy, and how each run is billed.
Every run thinks with **SuperCosmos by Clatter Labs**. Set `tier` when you create a run:
| `tier` | Behaviour | Use it for |
| --- | --- | --- |
| `auto` (default) | Cosmos routes each step | Most runs |
| `flash` | Fastest; answers without extended thinking | Small edits, scripts, lookups, high volume |
| `max` | Thinks before acting | Building features, debugging, multi-file changes |
| `heavy` | Thinks longest, longest answers | Hard bugs, large builds, deep reasoning |
## How runs are billed
Tokens are billed at the tier each call **actually ran on**. A run with `tier: "auto"` is billed at Flash rates. Computer time, tool actions, browser time and storage are billed the same way on every tier.
| Tier | Input / 1M tokens | Output / 1M tokens |
| --- | --- | --- |
| Flash | $1.60 | $3.40 |
| Max | $1.80 | $3.80 |
| Heavy | $2.00 | $4.40 |
**Long-context input above 262K tokens: 1.5×** (SuperCosmos): a request whose prompt is over 262K tokens bills its whole input at 1.5× the rate above.
Start with `auto` or `flash`. Move a run type to `max` or `heavy` only when you see it struggle: more steps, failed checks, or answers that miss the point.
See [SuperCosmos models](/models/overview) for more on each tier and [Rates](/billing/rates) for every price.
---
Source: https://developers.clatterlabs.com/agent/limits
# Limits and best practices
> The numbers that bound a run and a key, and how to work well within them.
## Limits
| Limit | Value |
| --- | --- |
| `input` length | 20,000 characters |
| `metadata` size | 2 KB (JSON) |
| Request body | 64 KB |
| Steps per run | 150 |
| Runs in progress per account | 5 (more answer `429 too_many_runs`) |
| Event stream connection | 10 minutes, then reconnect with `?after=` |
| Requests per minute | Per key: 10, 30 (default), 60 or 120 |
| API keys per account | 25 |
## Best practices
Never ship a `clsk_` key in a browser, mobile app or public repository. Call the API from your backend and keep the key in a secret manager or environment variable. Revoke it in the Console the moment it leaks.
Separate keys per service make logs readable and let you revoke one without breaking the rest. Give each key only the permissions it needs; a dashboard only needs `runs:read` and `account:read`.
One stream connection replaces dozens of `GET` calls and never touches your rate limit while it's open. If you poll, wait at least 2 seconds between calls.
On `429` wait for the `Retry-After` seconds before retrying. On `402 out_of_credits` stop creating runs and alert someone; retrying won't help.
Put your own ids in `metadata` (`{"ticket": "OPS-112"}`) so you can match runs to your records.
---
Source: https://developers.clatterlabs.com/agent/errors
# Errors
> Every error the Agent API returns, what it means, and what to do.
Errors are JSON with a stable `code` and a human-readable `message`:
```json
{ "error": { "code": "out_of_credits", "message": "You're out of Clatter Labs credits. ..." } }
```
| Status | `code` | Meaning | What to do |
| --- | --- | --- | --- |
| 400 | `bad_request` | Missing `input`, or a bad `tier` | Fix the request |
| 401 | `invalid_api_key` | The key is wrong or revoked | Check the key, or create a new one |
| 401 | `missing_account_id` | No `X-Clatter-Account` header | Send your Account ID |
| 401 | `account_mismatch` | The Account ID doesn't own this key | Use the key owner's Account ID |
| 402 | `out_of_credits` | Your credit balance is used up | See [Credits](/billing/credits) |
| 403 | `insufficient_scope` | The key lacks the permission | Create a key with that permission |
| 403 | `early_access` | Your account isn't in the early-access program yet | Ask for access |
| 403 | `no_cloud_account` | Your account hasn't been set up for Cosmos Agent | Sign in once to a Cosmos Agent app with this account, then retry. If it persists, visit the [Help Center](https://help.clatterlabs.com/agent-api/) |
| 403 | `account_suspended` | Your account is paused for 24 hours under the [Abuse policy](/policies/abuse) | Wait until `resets_at` (`Retry-After` seconds), or appeal through the [Help Center](https://help.clatterlabs.com/security-privacy/suspension/appeal-a-suspension) |
| 404 | `not_found` | No run with that id on your account | Check the id |
| 405 | `method_not_allowed` | Wrong HTTP method | See the endpoint's reference |
| 413 | `too_large` | `input`, `metadata` or the body is too big | See [Limits](/agent/limits) |
| 429 | `rate_limited` | Over the key's requests per minute | Wait `Retry-After` seconds |
| 429 | `too_many_runs` | 5 runs already in progress | Wait for one, or cancel one |
| 502 | `upstream` | Cosmos Cloud didn't answer | Retry with backoff |
| 503 | `unavailable` | The key couldn't be checked right now | Retry with backoff |
## Runs that fail
A run that starts but can't finish ends with `status: "failed"` and an `error`:
```json
"error": { "code": "out_of_credits", "message": "You're out of Clatter Labs credits." }
```
`code` is `out_of_credits` when the balance ran out midway, otherwise `run_failed`.
## Rate limit headers
Successful keyed responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`. A `429` adds `Retry-After` (seconds).
---
Source: https://developers.clatterlabs.com/line/overview
# Line CLI
> The fast terminal coding agent by Clatter Labs. Written in Rust, runs on SuperCosmos 1.1, with parallel sub-agents, MCP and native Arabic.
Line CLI (`line`) is a coding agent that lives in your terminal. It reads and edits your project, runs commands with your approval, and splits big jobs across parallel sub-agents on your machine.
```bash
curl -fsSL https://install.clatterlabs.xyz/line | sh # macOS / Linux
line login # sign in with your Clatter Labs account
line # start the agent in your project
```
macOS, Linux and Windows.Slash commands, flags and keys.Teach Line repeatable procedures with SKILL.md.Add tools, commands and hooks.
## Features
- **Streaming TUI** with Markdown, code and table rendering, multiline input (Shift+Enter, Alt+Enter or Ctrl+J), scrolling with the mouse wheel or PgUp/PgDn (the view stays put while output streams), Esc to interrupt, Ctrl+C to exit.
- **SuperCosmos 1.1**: **[SuperCosmos](/models/overview)** (efforts Flash, Max, Heavy, plus `auto` routing; 550B parameters, 55B active, 1M-token context). Switch effort with `/effort`. Line Code was retired on Nov 1, 2026; a saved Line Code choice moves to SuperCosmos automatically ([details](/models/line-code-retired)).
- **Local tools** with approval prompts: read, write, edit and multi-edit files (diff preview), move and delete, list folders, glob, grep, run shell commands (in the background too, for dev servers and watchers), read-only `git`, `diagnostics` (your project's own type checker, compiler or linter), a **repo map** (a ranked outline of the codebase, built with tree-sitter), Jupyter notebook edits, web search and fetch, and a visible to-do plan.
- **Parallel sub-agents**: the agent starts sub-agents on your machine to explore, research and review (read-only) or to do real work with full tools (general). Line locks files per agent, makes each agent read a file before editing it, and refuses an edit when the file changed since that agent read it, so parallel edits never overwrite each other. The **Agents panel** shows them live; `/agents` lists runs and their reports.
- **MCP**: connect MCP servers (stdio or HTTP) in `~/.line/mcp.json` or your project's `.mcp.json`; their tools appear to the agent. `/mcp` shows them, `line mcp` lists them from the shell. Project servers start only after you trust them.
- **Hooks**: run your own scripts on PreToolUse, PostToolUse, UserPromptSubmit, Stop and SessionStart (`/hooks`).
- **Project instructions**: `LINE.md` (or `AGENTS.md`) in the project and `~/.line/LINE.md` are always followed; `/init` writes one.
- **See every change**: `/diff` shows this session's changes (`/diff split` side by side), `/files` lists them by turn and agent; every file change is checkpointed, so `/undo` and `/rewind` take it back.
- **Context and usage**: a live context meter in the status bar, `/context` breaks the window down, and auto-compact starts at about 80% of the model's real context window. `/usage` shows how much of your plan's limits you've used and when they reset, credits, and tokens and cost per model; `/cost` this session.
- **Arabic, natively**: right-to-left text is shaped (joined letters), shown in the right order and right-aligned, mixed with English and code, in answers and in the input box. `/rtl` switches it (`terminal` if your terminal already handles bidi).
- **Plan mode and permission modes**: Shift+Tab cycles ask → accept edits → auto → plan.
- **@file mentions**, a live to-do panel, and a status bar with tokens, context and files changed.
- **Busy models don't fail your turn**: Line waits and retries with backoff, and shows it.
- **Skills and plugins** you control: nothing runs until you approve or enable it.
- **Sessions** saved locally; `line -c` continues the last one in a folder.
## Safety defaults
- Writes and shell commands ask first. **Shift+Tab** cycles the mode: ask, accept edits (file edits run, commands still ask), auto (nothing asks), plan (read-only); `line -y` starts in auto. Sub-agents follow the same mode; their approvals queue in the main window.
- Files that usually hold secrets (`.env`, SSH and cloud credentials, private keys) **always** ask, even with auto-approve on.
- Read-only commands that run without asking are limited to the project folder.
- Project MCP servers and hooks run only after you trust them.
- Commands Line runs never see Line's own sign-in token.
## Pricing
Line is covered by your [plan](/billing/credits) (Free included), with usage valued at the SuperCosmos [rate](/billing/rates) of the effort each call ran on (see [Models](/models)). Every plan, Free included, includes every effort.
---
Source: https://developers.clatterlabs.com/line/install
# Install Line CLI
> One command on macOS, Linux and Windows. Line updates itself.
```bash
curl -fsSL https://install.clatterlabs.xyz/line | sh
```
Builds are published for Linux (x86_64, aarch64) and macOS (Intel and Apple silicon).
In PowerShell:
```powershell
irm https://install.clatterlabs.xyz/line.ps1 | iex
```
## Sign in
```bash
line login
```
Line opens a sign-in with your Clatter Labs account (the **Line CLI** app). Approve it once; Line keeps the session on your machine. `line logout` signs out.
## Start
```bash
cd your-project
line
```
Run `/init` in a new project so Line writes a short guide to the codebase it can read in later sessions.
## Update
```bash
line update
```
`line update` and the install script always fetch the latest release, with checksums verified. What changed in each version is in the [changelog](/changelog).
Line CLI is in beta. Versions follow semver; pre-releases are marked `-beta`.
---
Source: https://developers.clatterlabs.com/line/commands
# Commands
> Flags, slash commands and keys in Line CLI.
## Flags
| Command | What it does |
| --- | --- |
| `line` | Start the agent in the current folder |
| `line "prompt"` | Start with a prompt |
| `line -c` | Continue the last session in this folder |
| `line -y` | Start in auto mode (no approval prompts) |
| `line -m -e ` | Model and effort for this run: `supercosmos` (`flash`, `max`, `heavy`), or `auto` |
| `line models` | List models and their efforts |
| `line -p "prompt"` | Print mode: answer once and exit (for scripts) |
| `line login` / `line logout` | Sign in or out |
| `line status` | Account, model and version |
| `line mcp` | List configured MCP servers and their tools (`line mcp trust ` trusts a project server) |
| `line update` | Update to the latest version |
| `line skill …` | Manage [skills](/line/skills) |
| `line plugin …` | Manage [plugins](/line/plugins) |
## Slash commands
Type `/` in the TUI for an autocomplete popup.
| Command | What it does |
| --- | --- |
| `/help` | All commands and keys |
| `/model` | Pick Auto or SuperCosmos (with its context window and size), then its effort |
| `/effort [name]` | Pick the effort: Flash, Max or Heavy |
| `/plan [task]` | Plan mode on/off: read-only research that ends in a plan to approve |
| `/mode ask\|accept-edits\|auto\|plan` | Permission mode (Shift+Tab cycles) |
| `/agents [n]` | Sub-agents: live status and this session's runs; `/agents ` shows one run's steps and report |
| `/diff [file] [split]` | This session's changes, unified or side by side |
| `/files` | Files changed this session, by turn and agent, with line counts |
| `/undo` | Revert the file changes of the last turn |
| `/rewind` | Go back to before an earlier prompt: files restored and the conversation cut there |
| `/bashes` | Background shells: list, output, kill |
| `/mcp` | MCP servers: status, tools, trust, reload |
| `/hooks` | Hooks: list and trust project hooks |
| `/todos` | Show the agent's current plan |
| `/context` | How much of the model's context window is in use, broken down |
| `/compact` | Summarize the conversation to free context |
| `/rtl auto\|on\|off\|terminal` | Arabic / right-to-left layout |
| `/mouse on\|off` | Mouse-wheel scrolling (hold Shift to select text while it's on) |
| `/new`, `/clear` | Start fresh |
| `/init` | Write `LINE.md` project instructions |
| `/skills`, `/plugins` | Manage skills and plugins |
| `/cost` | Tokens and cost of this session |
| `/usage` | How much of your plan's usage limits you've used and when they reset, credits, and tokens and cost per model |
| `/status` | Model, sign-in and project status |
| `/sessions`, `/resume` | Saved sessions |
| `/auto` | Toggle auto mode |
| `/config` | Settings |
| `/login`, `/logout`, `/update`, `/exit` | Account and app |
Plugins add their own commands as `/:`. Type `@` to attach a project file to your message (secret files and files outside the project are skipped).
`/undo`, `/rewind` and `/diff` cover changes made through Line's file tools; side effects of shell commands aren't tracked.
## Keys
| Key | Action |
| --- | --- |
| Enter | Send |
| Shift+Enter, Alt+Enter, Ctrl+J | New line |
| Shift+Tab | Cycle mode: ask → accept edits → auto → plan |
| Tab | Complete a command or an `@file` |
| ↑ / ↓ | Prompt history |
| Mouse wheel, PgUp / PgDn | Scroll the conversation (Shift/Ctrl+↑↓ one line, Ctrl+Home / Ctrl+End top / bottom) |
| Esc | Interrupt the current turn |
| Ctrl+C | Interrupt, clear the input, or exit |
---
Source: https://developers.clatterlabs.com/line/skills
# Skills
> Teach Line repeatable procedures with SKILL.md folders. Install, create and use them with your approval.
A skill is a folder with a `SKILL.md`: YAML front matter with a `name` and `description`, then Markdown instructions. It can carry scripts and reference files. This is the common SKILL.md format, so skills from public skill repositories work as they are.
```markdown
---
name: release-checklist
description: Prepare a release (version bump, changelog, tests, tag) without publishing anything.
---
# Steps
1. …
```
## Where skills live
```text
~/.line/skills// yours, every project
/.line/skills// shared with a repo (wins over yours with the same name)
plugins a plugin's skills, while it is enabled
```
## How the agent uses them
- Line's instructions list each skill's name and description only. When a task fits, the agent loads the full skill with `use_skill`.
- When a task needs a skill it doesn't have, the agent can propose one with `skill_install` (a GitHub path or URL, an https link to a SKILL.md, or a name from the default index). You see the source, every file (scripts are marked) and the start of SKILL.md. **Nothing is written until you approve**, and nothing in a skill runs on install.
- After working something out, the agent can save it with `skill_create` (you approve the text).
- Skill files are data: the agent follows a skill for the task you gave, never instructions that conflict with your request.
## Commands
```bash
line skill list
line skill search # searches the skill sources on GitHub
line skill install [--project] [-y]
line skill remove
line skill new [--project] # an empty SKILL.md to fill in
```
In the TUI: `/skills`, `/skills search `, `/skills install `, `/skills remove `, `/skills `.
Sources default to `anthropics/skills`. Add more with `skill_sources` in `~/.config/line/settings.json` or `LINE_SKILL_SOURCES=owner/repo,owner/repo/path`. Set `GITHUB_TOKEN` to raise GitHub's rate limit. Each skill is limited to 60 files and 2 MB.
---
Source: https://developers.clatterlabs.com/line/plugins
# Plugins
> Add tools the agent can call, slash commands, hooks and skills. Off until you enable them.
A plugin is a folder with a `plugin.json`. It can add **tools** the agent calls, **slash commands**, **hooks** that run around tool calls, and **skills**. Anyone can write one; nothing is compiled into Line.
```text
~/.line/plugins// yours, every project
/.line/plugins// shipped with a repo
```
## Trust model
Plugins run programs with your permissions. Line keeps them off until you say otherwise.
- A plugin never runs until you enable it (`line plugin enable ` or `/plugins enable `). Enabling shows every program it can run.
- Enabling records a fingerprint of **all** the plugin's files. If any file changes, the plugin is disabled until you review and enable it again. A cloned repo can't run code just by shipping `.line/plugins`.
- Plugin tools ask for approval like shell commands, unless the manifest marks them `"read_only": true`.
- Programs run in the project folder, without a shell (argv), with Line's credentials removed from the environment.
## Manifest
```json plugin.json
{
"name": "guard",
"version": "0.1.0",
"description": "What it does",
"tools": [{
"name": "deps",
"description": "Shown to the model",
"parameters": { "type": "object", "properties": { "path": { "type": "string" } } },
"read_only": true,
"timeout_secs": 30,
"command_unix": ["sh", "${PLUGIN_DIR}/tools/deps.sh"],
"command_windows": ["powershell", "-NoProfile", "-File", "${PLUGIN_DIR}/tools/deps.ps1"]
}],
"commands": [
{ "name": "audit", "description": "…", "prompt": "Review the dependencies. {{args}}" },
{ "name": "status", "description": "…", "run": ["git", "log", "--oneline", "-5"] }
],
"hooks": {
"session_start": [["sh", "${PLUGIN_DIR}/hooks/context.sh"]],
"pre_tool": [["sh", "${PLUGIN_DIR}/hooks/block.sh"]],
"post_tool": [],
"turn_end": []
},
"skills": "skills"
}
```
Exposed to the model as `__`. Arguments arrive as JSON on stdin; stdout is the result; a non-zero exit is reported as a failure. Environment: `LINE_PROJECT_DIR`, `LINE_PLUGIN_DIR`, `LINE_TOOL`. Use `command` (all systems) or `command_unix` / `command_windows`: an argv array, or a string run by `sh -c` / PowerShell.
Run as `/: [args]` (or `/` when no other plugin uses the name). `prompt` sends a prompt to the agent (`{{args}}` is what you typed after it); `run` executes a program and shows its output.
Each hook gets a JSON payload on stdin. `pre_tool` (`{"tool", "arguments"}`): exit code **2** blocks the call and stdout is the reason given to the model. `post_tool` (`{"tool", "arguments", "ok", "summary"}`) and `turn_end` observe. `session_start` runs at the start of each turn; its stdout (up to 4 KB) is added to the agent's context. Hooks time out after 15 seconds.
A folder of skills that are available while the plugin is enabled.
## Commands
```bash
line plugin new [--project] # scaffold (enabled: you wrote it)
line plugin install # copy into ~/.line/plugins (disabled)
line plugin info
line plugin enable|disable
line plugin remove
line plugin list
```
In the TUI: `/plugins`, `/plugins enable|disable `, `/plugins reload`.
---
Source: https://developers.clatterlabs.com/model-api/overview
# Model API
> Call SuperCosmos 1.1 from your own code with any OpenAI SDK. Pay as you go per token, from credits; new accounts get $5 of free credit.
The **Model API** lets you call **SuperCosmos 1.1**, Clatter Labs' model, straight from your own code. It speaks the OpenAI Chat Completions format, so any OpenAI SDK works by changing the base URL: streaming, tool calling and token usage included. You pay as you go per token from your credits, and every new account starts with **$5 of free credit**.
Create a key and make your first call in two minutes.`GET /v1/models` and `POST /v1/chat/completions`.
## At a glance
| | |
| --- | --- |
| Base URL | `https://api.gateway.clatterlabs.xyz/v1` |
| Format | OpenAI Chat Completions (stream and non-stream, tools, `usage`) |
| Auth | `Authorization: Bearer clsk_...` (permission `models:invoke`) + `X-Clatter-Account: CL-...` |
| Billing | Pay as you go per token, at the price of the model id you call |
| Free credit | $5 for every new account |
| Input | Text only |
## Models and prices
Each effort is its own model id:
| Model id | Model | Effort | Input / 1M tokens | Output / 1M tokens |
| --- | --- | --- | --- | --- |
| `supercosmos-flash` | SuperCosmos | Flash | $1.60 | $3.40 |
| `supercosmos-max` | SuperCosmos | Max | $1.80 | $3.80 |
| `supercosmos-heavy` | SuperCosmos | Heavy | $2.00 | $4.40 |
**Long-context input above 262K tokens: 1.5×** (SuperCosmos): a request whose prompt is over 262K tokens bills its whole input at 1.5× the rate above.
Output includes reasoning tokens. Prices are the same as everywhere else on Clatter Labs (see [Models](/models)). `GET /v1/models` returns the same list with prices.
You can also send the family id with an effort: `"model": "supercosmos"` plus `"effort"` (`flash` / `max` / `heavy`). `reasoning_effort` works too: `low`, `medium` and `high` map to the three efforts. Without an effort, the family id uses Flash.
Line Code ids (`line-code-fast`, `line-code-ultra`, `line-code-ultra-fast`) were retired on Nov 1, 2026 and answer `410 model_retired` ([details](/models/line-code-retired)).
## Billing
- **Credits only.** Model API calls are paid from your [credits](/billing/credits), pay as you go. Plans (Free included) don't cover API calls; they cover app usage like Line CLI, Cosmos Agent and Telegram. Buy credits in any amount from $1 to $800 per purchase.
- **$5 free credit.** Every new account starts with $5 of credit. Accounts that received the earlier one-time Model API trial spend what's left of it first.
- **Every model on every plan.** You pay the model's price.
- **Pay as you go.** Each call costs `input tokens × input price + output tokens × output price` for the model id you called, rounded up to the next millionth of a dollar. The `usage` in every response is what's billed. Input tokens include a short Clatter Labs instruction block added to every request.
- **Out of credits** answers `402 out_of_credits`.
- **Abuse policy.** Your API key acts for your account, so your end users' text counts against it. See the [Abuse policy](/policies/abuse).
Every call shows in the Console under **Logs** and **Usage** as *Model API*.
## Limits
- **Rate limit:** the key's own limit, 10 to 120 requests per minute, set when you create it (`429 rate_limited` with `Retry-After`).
- **Request size:** up to 3 MB and 800 messages; up to 64 tools.
- **Not supported:** image input, `n` > 1, `logprobs`, and the other OpenAI endpoints (embeddings, images, audio, files, responses).
---
Source: https://developers.clatterlabs.com/model-api/quickstart
# Model API quickstart
> Create a key with models:invoke, make your first call with cURL, Python or JavaScript, stream, and call tools.
## Before you start
You need a **Clatter Labs account** ([accounts.clatterlabs.com](https://accounts.clatterlabs.com)). New accounts get $5 of free credit, so you can try every model before adding anything.
In the [Console](https://console.clatterlabs.com/api-keys), go to **API keys › Create API key** and pick the **Model API** preset (permission `models:invoke`). The key starts with `clsk_` and is shown once. Your **Account ID** (like `CL-7K2M9QXA`) is in **Settings**.
```bash
export CLATTER_API_KEY="clsk_..." # Console › API keys
export CLATTER_ACCOUNT_ID="CL-XXXXXXXX" # Console › Settings
```
```bash cURL
curl https://api.gateway.clatterlabs.xyz/v1/chat/completions \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"model": "supercosmos-flash",
"messages": [{"role": "user", "content": "Write a haiku about the sea."}]
}'
```
```python Python
# pip install openai
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.gateway.clatterlabs.xyz/v1",
api_key=os.environ["CLATTER_API_KEY"],
default_headers={"X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"]},
)
resp = client.chat.completions.create(
model="supercosmos-flash",
messages=[{"role": "user", "content": "Write a haiku about the sea."}],
)
print(resp.choices[0].message.content)
print(resp.usage)
```
```javascript JavaScript
// npm install openai
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.gateway.clatterlabs.xyz/v1",
apiKey: process.env.CLATTER_API_KEY,
defaultHeaders: { "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID },
});
const resp = await client.chat.completions.create({
model: "supercosmos-flash",
messages: [{ role: "user", content: "Write a haiku about the sea." }],
});
console.log(resp.choices[0].message.content, resp.usage);
```
The response carries `usage` (`prompt_tokens`, `completion_tokens`). The same call shows in Console › **Logs** with its price, paid from your credits.
## Stream
Set `"stream": true` to get server-sent events in the OpenAI chunk format, ending with `data: [DONE]`. Add `"stream_options": {"include_usage": true}` for a final chunk with `usage` (the last content chunk also carries it).
```python
stream = client.chat.completions.create(
model="supercosmos-flash",
messages=[{"role": "user", "content": "Explain recursion in two sentences."}],
stream=True,
stream_options={"include_usage": True},
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
```
Max and Heavy think before answering. Their reasoning streams as `delta.reasoning_content` (and `message.reasoning_content` without streaming) and is billed as output.
## Call tools
Pass `tools` as OpenAI function definitions. When the model wants a tool, the reply has `tool_calls` and `finish_reason: "tool_calls"`; run the tool and send the result back as a `tool` message.
```python
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
},
}]
msgs = [{"role": "user", "content": "What's the weather in Paris?"}]
r = client.chat.completions.create(model="supercosmos-max", messages=msgs, tools=tools)
call = r.choices[0].message.tool_calls[0]
msgs += [r.choices[0].message, {"role": "tool", "tool_call_id": call.id, "content": '{"temp_c": 18, "sky": "light rain"}'}]
print(client.chat.completions.create(model="supercosmos-max", messages=msgs, tools=tools).choices[0].message.content)
```
## Pick a model
| If you need | Use |
| --- | --- |
| Fast, cheap answers and tool loops | `supercosmos-flash` |
| Planning, debugging, multi-step work | `supercosmos-max` |
| The hardest problems, long reasoning | `supercosmos-heavy` |
Prices for each are on the [Model API overview](/model-api/overview).
---
Source: https://developers.clatterlabs.com/code-buckets/overview
# Code Buckets
> Store your code and assets in buckets, organized by project. Every upload is encrypted, every change is recorded, and backups bring a bucket back in one step.
Code Buckets is Clatter Labs' storage for code. You group **buckets** into **projects**, upload your code as zip files (plus any assets, up to 10 GB per bucket), browse the code in the Console, follow an events feed of everything that happened, and back up and restore whole buckets.
Create a project and a bucket, upload a zip and read a file.Projects, buckets, uploads, preview, events and backups.
## What you get
| Feature | What it does |
| --- | --- |
| Projects and Project IDs | Every bucket belongs to a project with a stable ID like `cbp_4k9x2m7q1n8v3c6z0b5w` |
| Buckets up to 10 GB | Zips and assets, uploaded in resumable 16 MiB chunks with checksums |
| Code preview | Uploaded zips unpack into a file tree you can browse with syntax highlighting |
| Events | An ordered feed of every upload, code change, deletion, backup, restore and key action. No comments, no threads |
| Backups | Snapshot a bucket's code and stored files; restore it as a new version |
| Encryption | Every stored zip and asset is encrypted with AES-256-GCM under the bucket's own key |
| Fast API | A small HTTPS API on the edge; immutable reads are cached close to you |
## How it fits together
```text
Account (CL-…)
└── Project cbp_… ← the Project ID you use in the API
└── Bucket cbk_… ← up to 10 GB, its own encryption key
├── Objects cbo_… ← zips (archives) and assets, encrypted
├── Code tree ref ← unpacked from your latest zip, for preview
├── Events cbe_… ← what happened, newest first
└── Backups cbb_… ← snapshots you can restore
```
## Two ways to use it
- **Console**: [console.clatterlabs.com/code-buckets](https://console.clatterlabs.com/code-buckets). Create projects and buckets, drag in a zip, browse files, read events, back up and restore.
- **API**: `https://api.codebuckets.clatterlabs.xyz`, with a Console API key and your Account ID. Same projects and buckets, from your builds, scripts and agents.
## Base URL and authentication
```text
https://api.codebuckets.clatterlabs.xyz
```
Every request sends your API key and your Account ID:
```http
Authorization: Bearer clsk_...
X-Clatter-Account: CL-XXXXXXXX
```
Create the key in **Console › API keys** with the Code Buckets permissions (`buckets:read`, `buckets:write`, `backups:write`). See [Authentication](/api-reference/code-buckets/authentication).
The Free tier includes **1,000,000 tokens a month and 1 backup**. A token is one API request, or one MiB uploaded or downloaded. See [Pricing](/code-buckets/pricing).
---
Source: https://developers.clatterlabs.com/code-buckets/quickstart
# Quickstart
> Create a project and a bucket, upload a zip of your code, and read a file back, in about five minutes.
## Before you start
You need a **Clatter Labs account**. If you don't have one, create it at [accounts.clatterlabs.com](https://accounts.clatterlabs.com). Code Buckets is included free: 1,000,000 tokens a month and 1 backup.
Sign in to the [Console](https://console.clatterlabs.com). Your **Account ID** (like `CL-7K2M9QXA`) is on the Home page and in **Settings**.
Go to **API keys › Create key**, and tick **buckets:read**, **buckets:write** and **backups:write**. The key starts with `clsk_` and is shown only once.
```bash
export CLATTER_API_KEY="clsk_..." # Console › API keys
export CLATTER_ACCOUNT_ID="CL-XXXXXXXX" # Console › Settings
export CB="https://api.codebuckets.clatterlabs.xyz"
```
The response carries your **Project ID** (`cbp_…`).
```bash cURL
curl $CB/v1/projects \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{"name": "storefront"}'
```
```python Python
import os, requests
CB = "https://api.codebuckets.clatterlabs.xyz"
headers = {
"Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}",
"X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"],
}
project = requests.post(f"{CB}/v1/projects", headers=headers, json={"name": "storefront"}).json()
print(project["id"]) # cbp_...
```
```javascript JavaScript
const CB = "https://api.codebuckets.clatterlabs.xyz";
const headers = {
Authorization: `Bearer ${process.env.CLATTER_API_KEY}`,
"X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID,
"Content-Type": "application/json",
};
const project = await fetch(`${CB}/v1/projects`, { method: "POST", headers, body: JSON.stringify({ name: "storefront" }) }).then((r) => r.json());
console.log(project.id); // cbp_...
```
```bash
curl $CB/v1/projects/PROJECT_ID/buckets \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{"name": "web"}'
```
You get back the bucket id (`cbk_…`).
Uploads are chunked so big files work and can resume. Start the upload with the file's name and size, send each 16 MiB chunk, then complete it.
```bash cURL
FILE=storefront.zip
SIZE=$(wc -c < $FILE | tr -d ' ')
UP=$(curl -s $CB/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\": \"$FILE\", \"size\": $SIZE}" | jq -r .id)
split -b 16777216 -d -a 5 $FILE part-
i=0
for p in part-*; do
curl -s -X PUT $CB/v1/uploads/$UP/chunks/$i \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/octet-stream" --data-binary @$p > /dev/null
i=$((i+1))
done
curl -s -X POST $CB/v1/uploads/$UP/complete \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
```python Python
import os, requests
path = "storefront.zip"
size = os.path.getsize(path)
up = requests.post(f"{CB}/v1/buckets/{bucket_id}/uploads", headers=headers, json={"name": path, "size": size}).json()
with open(path, "rb") as f:
for i in range(up["chunk_count"]):
chunk = f.read(up["chunk_size"])
requests.put(f"{CB}/v1/uploads/{up['id']}/chunks/{i}", headers=headers, data=chunk).raise_for_status()
done = requests.post(f"{CB}/v1/uploads/{up['id']}/complete", headers=headers).json()
print(done["status"]) # processing, then ready
```
```javascript JavaScript
import { open, stat } from "node:fs/promises";
const path = "storefront.zip";
const { size } = await stat(path);
const up = await fetch(`${CB}/v1/buckets/${bucketId}/uploads`, { method: "POST", headers, body: JSON.stringify({ name: path, size }) }).then((r) => r.json());
const fh = await open(path);
for (let i = 0; i < up.chunk_count; i++) {
const buf = Buffer.alloc(Math.min(up.chunk_size, size - i * up.chunk_size));
await fh.read(buf, 0, buf.length, i * up.chunk_size);
const r = await fetch(`${CB}/v1/uploads/${up.id}/chunks/${i}`, { method: "PUT", headers: { ...headers, "Content-Type": "application/octet-stream" }, body: buf });
if (!r.ok) throw new Error((await r.json()).error.message);
}
await fh.close();
const done = await fetch(`${CB}/v1/uploads/${up.id}/complete`, { method: "POST", headers }).then((r) => r.json());
console.log(done.status); // processing, then ready
```
A few seconds later the zip is unpacked. List the tree and read a file:
```bash
curl "$CB/v1/buckets/BUCKET_ID/tree" \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
curl "$CB/v1/buckets/BUCKET_ID/files/README.md" \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
Or open the bucket in the [Console](https://console.clatterlabs.com/code-buckets) and click through the files.
```bash
curl $CB/v1/buckets/BUCKET_ID/backups \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" -d '{"name": "First backup"}'
```
## Next steps
Projects, buckets, objects and refs.Big files, resuming and checksums.Snapshot and restore.Every change, in order.
---
Source: https://developers.clatterlabs.com/code-buckets/concepts
# Concepts
> Projects, Project IDs, buckets, objects, the code tree, refs, events and backups.
## Projects and the Project ID
A **project** groups related buckets: an app, a client, a monorepo. Each project has a **Project ID** that starts with `cbp_`, like `cbp_4k9x2m7q1n8v3c6z0b5w`. It never changes, and it's how the API addresses the project (`/v1/projects/{project_id}/…`). The Console shows it with a copy button on the project page.
An account can have up to 100 projects.
## Buckets
A **bucket** lives in one project and holds your code and assets, up to **10 GB**. Its id starts with `cbk_`. Each bucket has:
- its own **encryption key** for everything stored in it ([Encryption](/code-buckets/encryption)),
- **stored objects**: the zips and assets you uploaded,
- a **code tree** built from your latest zip, for [preview](/code-buckets/preview),
- an **events** feed and **backups**.
A project can have up to 100 buckets.
## Objects: archives and assets
Everything you upload becomes an **object** (`cbo_…`):
| Kind | What it is | What happens |
| --- | --- | --- |
| `archive` | A `.zip` of code | Stored encrypted, and unpacked into the bucket's code tree (when preview is on) |
| `asset` | Any other file: images, builds, datasets, videos | Stored encrypted, downloadable as is |
Objects count toward the bucket's 10 GB. Deleting one frees its space.
## The code tree and refs
When a zip finishes uploading, Code Buckets unpacks it into the bucket's **code tree**. Each version of the tree has a **ref**: a 40-character id like `9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0`.
- `bucket.code.ref` is the current version.
- `code.updated` events and backups record the ref they produced or captured.
- Reading with an explicit `?ref=` always returns the same content, so those responses are cached and fast.
A zip replaces the whole tree, or only one folder if you upload it with `target_path` (like `packages/api`).
## Events
Code Buckets has no comments or threads. Instead every action is an **event** (`cbe_…`) in an ordered feed: uploads, code changes, deletions, backups, restores, settings changes and key actions, each with who did it (which API key, or the Console). See [Events](/code-buckets/events).
## Backups
A **backup** (`cbb_…`) captures a bucket's code tree and the list of its stored objects. Restoring puts that tree back as a new version and brings back objects deleted since. See [Backups](/code-buckets/backups).
## Tokens
Code Buckets usage is counted in **tokens**: 1 per API request, plus 1 per MiB uploaded or downloaded. The Free tier includes 1,000,000 a month. See [Pricing](/code-buckets/pricing).
## IDs at a glance
| Prefix | What |
| --- | --- |
| `cbp_` | Project (the Project ID) |
| `cbk_` | Bucket |
| `cbo_` | Upload / stored object |
| `cbe_` | Event |
| `cbb_` | Backup |
| `CL-` | Your Account ID |
---
Source: https://developers.clatterlabs.com/code-buckets/uploads
# Uploads
> Chunked, resumable uploads for zips and assets up to 10 GB per bucket.
Every upload, small or large, works the same way:
1. **Start** it with the file's `name` and exact `size`: [`POST /v1/buckets/{bucket_id}/uploads`](/api-reference/code-buckets/uploads/create). You get an upload id, `chunk_size` (16,777,216 bytes = 16 MiB) and `chunk_count`.
2. **Send each chunk**: [`PUT /v1/uploads/{upload_id}/chunks/{index}`](/api-reference/code-buckets/uploads/chunk) with the raw bytes. Chunk `i` is bytes `i × chunk_size` to `(i + 1) × chunk_size - 1`; only the last chunk is shorter.
3. **Complete** it: [`POST /v1/uploads/{upload_id}/complete`](/api-reference/code-buckets/uploads/complete).
A file under 16 MiB is one chunk.
## Zips or assets
- A `.zip` is stored as an **archive** and unpacked into the code tree. Upload it with `"target_path": "packages/api"` to replace only that folder.
- Anything else is an **asset**. Set `"kind": "asset"` to store a zip as a plain file instead of unpacking it.
## Parallel chunks
Chunks can go in any order and at the same time. Three or four at once is a good default. Chunk requests don't count toward your key's per-minute limit (they have their own generous limit), but they do count as tokens: 1 per request plus 1 per MiB.
## Checksums
Send `X-Content-SHA256: ` with each chunk and the API refuses it with `400 checksum_mismatch` if the bytes changed on the way. Every response also returns the chunk's `sha256`.
## Resuming
If the connection drops, nothing is lost. Ask which chunks arrived and send the rest:
```bash
curl $CB/v1/uploads/UPLOAD_ID \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
# { "object": "upload", "status": "uploading", "chunk_count": 8, "received_chunks": [0, 1, 2, 5], ... }
```
Sending a chunk twice is safe: the same bytes answer `"duplicate": true`, different bytes replace it.
## A complete uploader
```python Python
import concurrent.futures, hashlib, os, requests
CB = "https://api.codebuckets.clatterlabs.xyz"
H = {"Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}", "X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"]}
def upload(bucket_id, path, resume_id=None):
size = os.path.getsize(path)
if resume_id:
up = requests.get(f"{CB}/v1/uploads/{resume_id}", headers=H).json()
else:
up = requests.post(f"{CB}/v1/buckets/{bucket_id}/uploads", headers=H, json={"name": os.path.basename(path), "size": size}).json()
have = set(up.get("received_chunks") or [])
def send(i):
with open(path, "rb") as f:
f.seek(i * up["chunk_size"])
data = f.read(up["chunk_size"])
for attempt in range(5):
r = requests.put(f"{CB}/v1/uploads/{up['id']}/chunks/{i}", data=data,
headers={**H, "Content-Type": "application/octet-stream", "X-Content-SHA256": hashlib.sha256(data).hexdigest()})
if r.ok:
return
if r.status_code < 500 and r.status_code != 429:
raise RuntimeError(r.json()["error"]["message"])
raise RuntimeError(f"chunk {i} kept failing; resume with upload id {up['id']}")
with concurrent.futures.ThreadPoolExecutor(4) as pool:
list(pool.map(send, [i for i in range(up["chunk_count"]) if i not in have]))
return requests.post(f"{CB}/v1/uploads/{up['id']}/complete", headers=H).json()
print(upload("cbk_...", "storefront.zip"))
```
```javascript JavaScript
import { createHash } from "node:crypto";
import { open, stat } from "node:fs/promises";
import { basename } from "node:path";
const CB = "https://api.codebuckets.clatterlabs.xyz";
const H = { Authorization: `Bearer ${process.env.CLATTER_API_KEY}`, "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID };
async function upload(bucketId, path, resumeId) {
const { size } = await stat(path);
const up = resumeId
? await fetch(`${CB}/v1/uploads/${resumeId}`, { headers: H }).then((r) => r.json())
: await fetch(`${CB}/v1/buckets/${bucketId}/uploads`, { method: "POST", headers: { ...H, "Content-Type": "application/json" }, body: JSON.stringify({ name: basename(path), size }) }).then((r) => r.json());
const have = new Set(up.received_chunks ?? []);
const todo = [...Array(up.chunk_count).keys()].filter((i) => !have.has(i));
const fh = await open(path);
const send = async () => {
for (let i; (i = todo.shift()) !== undefined; ) {
const buf = Buffer.alloc(Math.min(up.chunk_size, size - i * up.chunk_size));
await fh.read(buf, 0, buf.length, i * up.chunk_size);
const sha = createHash("sha256").update(buf).digest("hex");
for (let attempt = 0; ; attempt++) {
const r = await fetch(`${CB}/v1/uploads/${up.id}/chunks/${i}`, { method: "PUT", headers: { ...H, "Content-Type": "application/octet-stream", "X-Content-SHA256": sha }, body: buf });
if (r.ok) break;
if ((r.status < 500 && r.status !== 429) || attempt === 4) throw new Error((await r.json()).error.message);
}
}
};
await Promise.all([send(), send(), send(), send()]);
await fh.close();
return fetch(`${CB}/v1/uploads/${up.id}/complete`, { method: "POST", headers: H }).then((r) => r.json());
}
console.log(await upload("cbk_...", "storefront.zip"));
```
## After completing
- An **asset** is `ready` immediately.
- An **archive** in a bucket with preview on is `processing` while its tree is built (usually a few seconds; longer for very large zips), then `ready`. Poll [Get an upload](/api-reference/code-buckets/uploads/get) or watch for the `code.updated` event.
## Space
Starting an upload reserves its size. If the bucket's stored files plus unfinished uploads plus the new file would pass 10 GB, the start answers `413 bucket_full`. [Abort](/api-reference/code-buckets/uploads/abort) uploads you won't finish to free their space.
---
Source: https://developers.clatterlabs.com/code-buckets/public-files
# Public files
> Share stored files with a public link, or keep them private (the default). Images get their own fast host.
Every file in a bucket is **private** by default: it can only be read with an API key and your Account ID, or in the Console. Make a file **public** and it gets a link anyone can open.
Public links live on two hosts, picked by what the file is:
| File | Public link | Cache |
| --- | --- | --- |
| **Images** (`image/*`: PNG, JPEG, GIF, WebP, AVIF, SVG, ICO…) | `https://img.cdn.clatterlabs.xyz/` | 1 year, `immutable` |
| **Everything else** (code, static files, archives, video, PDFs…) | `https://files.cdn-buckets.clatterlabs.xyz//` | 60 seconds |
```
https://img.cdn.clatterlabs.xyz/V1StGXR8Z5jdHi6BmyT2kq
https://files.cdn-buckets.clatterlabs.xyz/cbo_x4p8t2w6r1k9m3q7n5d0/app.js
```
Both are served decrypted on our servers, with the right `Content-Type`, edge caching and `ETag`. Private files are never served: their links answer `404`, the same as a link that doesn't exist. You don't pick the host: `public_url` in every response is already the right link, and `served_as` says which kind it is (`image` or `file`).
## Images: img.cdn.clatterlabs.xyz
- The link is an **opaque id** (22 letters and digits), with no file name, bucket or object id in it.
- A file counts as an image when its upload's `content_type` is `image/*`, or, when that was empty or `application/octet-stream`, when its extension is an image one (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.svg`, `.ico`, `.bmp`, `.tif`, `.heic`, `.jxl`).
- Served with that `Content-Type` and `Cache-Control: public, max-age=31536000, immutable`: a stored file never changes, so browsers and CDNs can keep it for a year. Put these links straight into `` tags, Markdown, emails or OG tags.
- When an image stops being public, its id is **retired for good**: the old link answers `404` and keeps doing so, even if you make the image public again (it then gets a new id and a new `public_url`). Browsers that already loaded the image may still show their cached copy.
- An older `files.cdn-buckets.clatterlabs.xyz` link to an image redirects (`308`) to its image link. Add `?download=1` to download the original from the files host instead.
## Files: files.cdn-buckets.clatterlabs.xyz
`https://files.cdn-buckets.clatterlabs.xyz//`
- The file name at the end is for people and tools; the object id identifies the file.
- `Content-Type` comes from the upload's `content_type`, or from the file extension when it was `application/octet-stream`.
- Opens inline in the browser; add `?download=1` to download it as an attachment.
- Supports `HEAD`, single `Range` requests (`206 Partial Content`, so large videos and files stream and resume), and `ETag` / `If-None-Match` (`304`).
- HTML, SVG and XML files are served with a sandboxing `Content-Security-Policy`, so they can't run scripts on our domain.
- `Cache-Control: public, max-age=60, must-revalidate`.
Both hosts allow CORS from any website (`Access-Control-Allow-Origin: *`).
## File or bucket
- A **bucket** is `private` (the default) or `public`.
- A **file** (a stored zip or asset) is `inherit` (the default: follow the bucket), `private` or `public`.
What applies is the file's own setting, or the bucket's when the file is `inherit`. So you can make one image public in a private bucket, or keep one file private in a public bucket. The response's `effective_visibility` and `public_url` always tell you the result.
The **code preview tree** (the files unpacked from your zips) is never public. To publish a file from your code, upload it as an asset.
## Make a file public
```bash cURL
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"}'
# { "object": "object", "name": "hero.png", "visibility": "public", "effective_visibility": "public",
# "public_url": "https://img.cdn.clatterlabs.xyz/V1StGXR8Z5jdHi6BmyT2kq", "served_as": "image", ... }
```
```python Python
import os, requests
CB = "https://api.codebuckets.clatterlabs.xyz"
H = {"Authorization": f"Bearer {os.environ['CLATTER_API_KEY']}", "X-Clatter-Account": os.environ["CLATTER_ACCOUNT_ID"]}
r = requests.patch(f"{CB}/v1/buckets/{bucket_id}/objects/{object_id}/visibility", headers=H, json={"visibility": "public"})
r.raise_for_status()
print(r.json()["public_url"]) # img.cdn.clatterlabs.xyz/ for images, files.cdn-buckets.clatterlabs.xyz/... otherwise
```
```javascript JavaScript
const CB = "https://api.codebuckets.clatterlabs.xyz";
const headers = { Authorization: `Bearer ${process.env.CLATTER_API_KEY}`, "X-Clatter-Account": process.env.CLATTER_ACCOUNT_ID, "Content-Type": "application/json" };
const r = await fetch(`${CB}/v1/buckets/${bucketId}/objects/${objectId}/visibility`, { method: "PATCH", headers, body: JSON.stringify({ visibility: "public" }) });
console.log((await r.json()).public_url);
```
You can also upload straight to public: pass `"visibility": "public"` (and the right `content_type`, like `image/png`) when you [start the upload](/api-reference/code-buckets/uploads/create), and `public_url` works as soon as the upload completes.
To make a whole bucket public, use [Set bucket visibility](/api-reference/code-buckets/visibility/bucket). [Get a public URL](/api-reference/code-buckets/visibility/public-url) returns a file's link at any time, with `public` telling you whether it works right now.
## Make it private again
Send `"visibility": "private"` (or `"inherit"` in a private bucket). The link stops working on the next request: every request to the public hosts checks the file's visibility first, and edge-cached parts of a file are only served after that check. An image's id is retired at the same moment (see above). Copies already in someone's browser are out of our reach: up to 60 seconds for files, longer for images, which are cached as immutable.
Deleting a public file also turns its link off.
## Events
Every change is in the [events feed](/code-buckets/events): `object.visibility_changed` (with `from`, `to`, `effective` and `public_url` in `data`) and `bucket.visibility_changed` (with `from`, `to` and how many files follow the bucket).
## Tokens
Changing visibility is a normal request: 1 token. Traffic to your public links (both hosts) is counted for your account at the same rate as API downloads (1 token per request + 1 per MiB sent) and shows in [Get usage](/api-reference/code-buckets/usage) under `storage.public_files`.
## In the Console
Open a bucket › **Uploads & files** and pick **Public**, **Private** or **Bucket default** next to a file. Public files show their link with a copy button, and images a thumbnail served from the images host. The bucket's own default is in **Settings › Access**.
---
Source: https://developers.clatterlabs.com/code-buckets/preview
# Preview
> Browse a bucket's code as a file tree, with syntax highlighting, in the Console or over the API.
When a zip finishes uploading to a bucket with **preview** on, Code Buckets unpacks it into the bucket's code tree. The Console's **Files** tab shows that tree with a search box and a highlighted viewer; the API gives you the same tree and files.
## What gets unpacked
- If every file in the zip sits inside one top folder (like `storefront-main/`, the usual shape of downloaded zips), that folder is dropped so your files start at the root. The object's `preview.stripped_folder` says which.
- Files up to **2 MB** each go into the tree, up to about 96 MB and 20,000 files per zip. Bigger files, and anything past those limits, stay safely in the stored zip; `preview.skipped` counts them and `preview.skipped_examples` names some.
- Paths that try to leave the tree (`../`), `.git/`, `__MACOSX/` and `.DS_Store` are skipped. Password-protected zip entries can't be previewed.
The object's `preview.status` ends as `ready`, `partial` (some files kept in the zip only) or `failed` (the zip couldn't be read; it's still stored).
## Reading the tree
```bash
curl "$CB/v1/buckets/BUCKET_ID/tree" \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
```json
{
"object": "tree",
"ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"files": [
{ "path": "README.md", "type": "file", "size": 1840 },
{ "path": "src", "type": "dir" },
{ "path": "src/index.ts", "type": "file", "size": 5121 }
],
"truncated": false
}
```
## Reading a file
```bash
curl "$CB/v1/buckets/BUCKET_ID/files/src/index.ts?ref=9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0" \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
The response has `content` (UTF-8 text, or base64 for binary files) and a `language` (`typescript`, `python`, `json`, …) you can hand to a highlighter. Add `download=1` for the raw bytes.
Pass `?ref=` whenever you can. Responses for an explicit ref never change, so they're cached at the edge and come back in milliseconds.
## Turning preview off
Set `"preview": false` when you create or [update](/api-reference/code-buckets/buckets/update) a bucket to keep its code only in encrypted zips. New zips are then stored without being unpacked (`preview.status: "off"`); download them to read them.
---
Source: https://developers.clatterlabs.com/code-buckets/events
# Events
> An ordered feed of everything that happens in a project or bucket. Code Buckets uses events instead of comments.
Every action that changes something writes an event: who did it, what changed, and when. Read a bucket's feed with [List bucket events](/api-reference/code-buckets/buckets/events) or a whole project's with [List project events](/api-reference/code-buckets/projects/events). The Console shows the same feeds on the project and bucket pages.
```json
{
"object": "event",
"id": "cbe_7y2u5i8o1p4a6s9d3f0g",
"type": "backup.restored",
"summary": "Backup \"Before checkout rewrite\" restored, 1 objects brought back",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"actor": { "type": "api_key", "key_id": "key_7f3a…", "key_name": "CI" },
"data": { "backup_id": "cbb_h3g7f1d9s5a2q8w4e6r0", "ref": "3e8d0b7c…", "objects_mode": "keep", "revived": 1, "hidden": 0 },
"at": "2026-10-28T14:21:03.552Z"
}
```
## Event types
| Type | When |
| --- | --- |
| `project.created`, `project.updated`, `project.deleted` | A project was created, renamed or deleted |
| `bucket.created`, `bucket.updated`, `bucket.deleted` | A bucket was created (with its own AES-256-GCM data key), changed (name, preview) or deleted |
| `encryption.key_created` | Older buckets only: the bucket's data key was created. New buckets note this in `bucket.created` |
| `upload.started` | An upload was opened (name, size, chunks) |
| `upload.completed` | All chunks arrived and the file was stored, encrypted |
| `upload.aborted` | An unfinished upload was cancelled |
| `code.updated` | A zip was unpacked into a new code tree (`data.ref`, `files`, `skipped`) |
| `code.update_failed` | A zip couldn't be unpacked; it's still stored |
| `object.deleted` | A stored zip or asset was deleted |
| `object.visibility_changed` | A file was made public, private or set to follow its bucket (`data.from`, `to`, `effective`, `public_url`). See [Public files](/code-buckets/public-files) |
| `bucket.visibility_changed` | A bucket was made public or private (`data.from`, `to`, `files_following`) |
| `backup.created`, `backup.replaced`, `backup.deleted` | Backups were made, replaced (Free tier) or deleted |
| `backup.restored` | A backup was restored (`data.ref`, `revived`, `hidden`) |
## Who did it
`actor` says where the change came from:
- `{ "type": "api_key", "key_id", "key_name" }`: a request made with that API key,
- `{ "type": "console" }`: you, in the Console,
- `{ "type": "system" }`: Code Buckets itself (for example, finishing a preview).
## Paging and filtering
Events come newest first, 50 per page by default (up to 100 with `limit`). When `has_more` is true, pass `next_before` as `before` to get older ones. Filter with `type=backup.restored`, or a prefix like `type=upload.`.
---
Source: https://developers.clatterlabs.com/code-buckets/backups
# Backups
> Snapshot a bucket's code and stored files, and bring it back in one step.
A **backup** captures two things about a bucket:
- its **code tree** (the current `ref`), and
- the list of its **stored objects** (zips and assets).
## Create a backup
```bash
curl $CB/v1/buckets/BUCKET_ID/backups \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" -d '{"name": "Before checkout rewrite"}'
```
Backups need the `backups:write` permission. Taking one is quick: nothing is copied, the backup points at the stored data, which stays as long as the backup exists.
## Restore
```bash
curl -X POST $CB/v1/backups/BACKUP_ID/restore \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
Restoring:
1. puts the backup's code tree back as a **new version** of the tree. The version you had before stays reachable by its ref (it's in the `code.updated` and `backup.restored` events), so a restore never destroys work;
2. brings back stored objects from the backup that were deleted since;
3. by default keeps objects added after the backup. Send `{"objects": "exact"}` to hide those too, so the stored files match the backup exactly.
A `backup.restored` event records what happened.
## How many backups
| Plan | Backups |
| --- | --- |
| Free | 1 per account (across all buckets) |
| Need more? | [Contact us](https://help.clatterlabs.com/code-buckets/troubleshooting/cb-contact-support) |
On the Free tier, creating a second backup answers `409 backup_limit` with the id of the one you have. Send `"replace": true` to replace it, or [delete it](/api-reference/code-buckets/backups/delete) first. Restoring is free and unlimited.
---
Source: https://developers.clatterlabs.com/code-buckets/encryption
# Encryption
> What's encrypted, how, and who holds the keys.
## Stored zips and assets
Every file you upload is split into 16 MiB chunks, and **each chunk is encrypted with AES-256-GCM before it's stored**:
- Each bucket has its **own 256-bit data key**, created with the bucket (noted in its `bucket.created` event).
- Every chunk gets a fresh random 96-bit nonce and is bound to its object and position, so chunks can't be swapped or replayed into another file without failing authentication.
- The bucket's data key is never stored in plain form: it's **wrapped (encrypted) by a Clatter Labs master key** that lives only in our servers' secret configuration and is never sent to clients, logged, or kept with the data.
- Downloads are decrypted on the fly and verified; a tampered chunk fails instead of returning wrong bytes.
## The browsable code tree
When **preview** is on, the code unpacked from your zips is kept in private, access-controlled storage so it can be listed and read quickly. That copy is **not** encrypted with your bucket's data key. If a bucket must hold code only in encrypted form, turn preview off for it: new zips are then stored encrypted and never unpacked.
## Public files
Files you make [public](/code-buckets/public-files) stay encrypted in storage. When someone opens a public link, the file is decrypted on Code Buckets' servers and sent over HTTPS. Private files are never decrypted for the public hosts (img.cdn.clatterlabs.xyz for images, files.cdn-buckets.clatterlabs.xyz for everything else).
## In transit
All API and Console traffic uses HTTPS (TLS). Send `X-Content-SHA256` with each chunk to make sure what arrived is exactly what you sent.
## Access
Only requests with a valid API key **and** the matching Account ID (or your signed-in Console session) can read a bucket. Keys carry only the permissions you give them, and you can revoke them at any time in the Console.
## Summary
| Data | Protection |
| --- | --- |
| Uploaded zips and assets | AES-256-GCM per chunk, per-bucket data key wrapped by a Clatter Labs master key |
| Code tree (preview on) | Private, access-controlled storage; not encrypted with the bucket key |
| Projects, buckets, events, backups (metadata) | Private database, accessed only by Code Buckets' servers |
| Public files | Stored encrypted like any other; decrypted on our servers only when their public link is opened |
| Traffic | HTTPS |
---
Source: https://developers.clatterlabs.com/code-buckets/pricing
# Pricing
> Code Buckets is metered in tokens: 1,000,000 a month and 1 backup on every plan, with storage from 10 GB (Free) to 2 TB (Ultra).
## Tokens
A **Code Buckets token** is the unit of API usage:
| Action | Tokens |
| --- | --- |
| Any API request | 1 |
| File data uploaded (chunks) | 1 per MiB (rounded up per request) |
| File data downloaded (chunks, objects, `download=1` files) | 1 per MiB (rounded up per request) |
JSON request and response bodies (listing, previewing files, events) cost only the request token.
Examples:
- Listing projects: **1** token.
- Uploading a 100 MiB zip: 7 chunks → 7 requests + 100 MiB of data = **107** tokens, plus 2 for starting and completing.
- Downloading a 1 GB asset: about **1,025** tokens.
In the Console, browsing is free; data you upload or download there counts 1 token per MiB. Every API response includes an `X-Codebuckets-Tokens` header with what that request used.
## Plans
Code Buckets storage comes with your Clatter Labs [plan](/billing/credits):
| | Free | Developer | Plus | Pro | Max | Ultra |
| --- | --- | --- | --- | --- | --- | --- |
| Storage (all buckets) | 1 GB | 25 GB | 50 GB | 150 GB | 400 GB | 1 TB |
| Tokens | 1,000,000 per month | 1,000,000 per month | 1,000,000 per month | 1,000,000 per month | 1,000,000 per month | 1,000,000 per month |
| Backups | 1 | 1 | 1 | 1 | 1 | 1 |
| Largest bucket | 10 GB | 10 GB | 10 GB | 10 GB | 10 GB | 10 GB |
The month runs on the UTC calendar. When the month's tokens are used up, requests answer `402 quota_exceeded` until the next month. An upload that would go past your plan's storage answers `402 storage_full` in the Console. **Need more? [Contact us](https://help.clatterlabs.com/code-buckets/troubleshooting/cb-contact-support).**
## Checking usage
```bash
curl https://api.codebuckets.clatterlabs.xyz/v1/usage \
-H "Authorization: Bearer $CLATTER_API_KEY" -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
The Console shows the same numbers on the Code Buckets page.
---
Source: https://developers.clatterlabs.com/code-buckets/limits
# Limits
> The numbers that bound projects, buckets, uploads and requests.
| Limit | Value |
| --- | --- |
| Storage per bucket | 10 GB (10,737,418,240 bytes), counting stored zips and assets plus unfinished uploads |
| Chunk size | 16 MiB (16,777,216 bytes); the last chunk is shorter |
| Chunks per file | 1,000 |
| Whole-file download | Up to 1 GB; larger objects download chunk by chunk |
| Projects per account | 100 |
| Buckets per project | 100 |
| Preview: file size | 2 MB per file (bigger files stay in the zip) |
| Preview: per zip | about 96 MB of files and 20,000 files |
| Names | 80 characters (projects, buckets, backups); file names 255 |
| Descriptions | 500 characters |
| JSON request body | 16 KB |
| Requests per minute | Per key: 10, 30 (default), 60 or 120. Chunk uploads and downloads don't count toward it |
| Backups | Free: 1 per account |
| Tokens | Free: 1,000,000 per month (UTC calendar month) |
## Best practices
Never ship a `clsk_` key in a browser, mobile app or public repository. Give each integration its own key with only the permissions it needs; a CI job that uploads needs `buckets:write`, a dashboard only `buckets:read`.
Send 3 or 4 chunks at a time and retry a failed chunk. If the process dies, read `received_chunks` and send only what's missing.
Tree and file reads with `?ref=` are cached at the edge. Read `bucket.code.ref` once and reuse it.
Take a backup before uploading a zip that replaces the whole tree. Restoring is free.
---
Source: https://developers.clatterlabs.com/console/overview
# Clatter Labs Console
> Manage API keys, see usage and logs, and keep an eye on your credits.
The [Console](https://console.clatterlabs.com) is where you manage everything you build with Clatter Labs. Sign in with your Clatter Labs account.
| Section | What's there |
| --- | --- |
| **Home** | Your Account ID (with copy), balance and quick links |
| **API keys** | Create, scope, rate-limit and revoke Agent API keys |
| **Models** | SuperCosmos tiers and their prices |
| **Logs** | Recent API runs with status, tier and usage |
| **Usage** | Spend and tokens by day, product and tier |
| **Billing** | Plan, usage meters (% used and reset time), Code Buckets storage, API credits (top up $1–$800), usage and history |
| **Team**, **Settings** | Organization and account settings, including your Account ID |
| **Developer docs** | Opens these docs |
The Console works in light and dark mode and on phones.
Create and manage keys.How plans, limits and credits work.
---
Source: https://developers.clatterlabs.com/console/api-keys
# API keys
> Create, scope, rate-limit and revoke Agent API keys in the Console.
## Create a key
In the [Console](https://console.clatterlabs.com/api-keys), go to **API keys** › **Create key**.
| Permission | Allows |
| --- | --- |
| `runs:write` | Create and cancel runs |
| `runs:read` | Read runs, events and results |
| `account:read` | Read credit balance and usage |
| `models:invoke` | Call models through the [Model API](/model-api/overview) |
10, 30 (default), 60 or 120 requests per minute. Each key has its own limit.
The key (`clsk_…`) is shown **once**. Clatter Labs stores only a keyed hash, so a lost key can't be recovered; create a new one.
## Use it
Send the key with your **Account ID** on every request:
```http
Authorization: Bearer clsk_...
X-Clatter-Account: CL-XXXXXXXX
```
The Account ID must be the key owner's. This means a key copied out of a log isn't enough on its own.
## Revoke
Revoke a key from **API keys** at any time. Requests with it fail right away with `401 invalid_api_key`, and an open event stream ends with an `error` event.
## Limits
An account can hold up to **25** keys.
Never put a key in front-end code, a mobile app, a public repo or a screenshot. If one leaks, revoke it first, then rotate.
---
Source: https://developers.clatterlabs.com/billing/credits
# Plans and credits
> Every plan includes every model and tool, Line CLI, Cosmos Agent (Telegram included), Code Buckets and pay-as-you-go access to the Model API and Agent API. Compare plans, usage resets and credits.
Clatter Labs billing has two parts, and every account has both:
- A **plan** covers **app usage**: [Line CLI](/line/overview), Cosmos Agent (including Cosmos Agent on Telegram) and [Code Buckets](/code-buckets/overview) storage. Every plan, Free included, has **every model and every tool**.
- **Credits** (US dollars) pay for **API usage**: the [Model API](/model-api/overview) and the [Agent API](/agent/overview), pay as you go, on every plan. Plans never cover API calls.
New accounts start with **$5 of free credit**.
## Plans
| | Free | Developer | Plus | Pro | Max | Ultra |
| --- | --- | --- | --- | --- | --- | --- |
| Price | $0 | $15 / month | $25 / month | $50 / month | $100 / month | $200 / month |
| Usage compared with Free | 1× | ≈15× | ≈35× | ≈55× | ≈125× | ≈280× |
| Compared with the plan below | — | ≈15× Free | ≈2.5× Developer | ≈1.6× Plus | ≈2.3× Pro | ≈2.2× Max |
| Usage window resets every | Monthly allowance | 5.5 hours | 5.5 hours | 5 hours | 2 hours | 1.5 hours |
| Weekly usage resets | — | Every 7 days | Every 7 days | Every 7 days | Every 7 days | Every 7 days |
| Every model and tool | Yes | Yes | Yes | Yes | Yes | Yes |
| Line CLI, Cosmos Agent | Yes | Yes | Yes | Yes | Yes | Yes |
| Cosmos Agent on Telegram | Yes | Yes | Yes | Yes | Yes | Yes |
| Code Buckets storage | 1 GB | 25 GB | 50 GB | 150 GB | 400 GB | 1 TB |
| Model API and Agent API | Pay as you go | Pay as you go | Pay as you go | Pay as you go | Pay as you go | Pay as you go |
Usage multiples are approximate and compare typical use across the models; what you actually get depends on which models and efforts you use. Each step up gives more usage per window and per week. Plans are monthly memberships, bought in the Console under **Billing › Plans** (checkout by Gumroad); you can change or cancel from **Billing**.
## How usage limits work
Usage is measured as what your requests would cost at the [model rates](/billing/rates), across Line CLI, Cosmos Agent and Cosmos Agent on Telegram together. Clatter Labs doesn't publish fixed amounts; the Console shows **how much of each limit you've used (in %) and when it resets**.
- **Usage window** (paid plans): a window starts with your first request after the previous one ended and lasts the plan's window length (5.5 h on Developer and Plus, 5 h on Pro, 2 h on Max, 1.5 h on Ultra).
- **Weekly limit** (paid plans): runs for 7 days from your billing date, then starts again.
- **Monthly allowance** (Free): resets on the 1st of every month (UTC).
- At a limit, new app requests answer **HTTP 429** with `window_limit_reached`, `weekly_limit_reached` or `monthly_limit_reached`, plus `resets_at` and `Retry-After`. Line CLI shows the message with the reset time.
- Cosmos Agent on Telegram also keeps its own daily limit per account; whichever is reached first applies.
- **Teams:** a team member uses the team owner's plan and credits, within the access and limits the owner sets in the Console under **Team**. A request outside that access answers **HTTP 403** `team_scope_denied`; past the member's daily quota or monthly spending limit it answers **HTTP 429** `team_daily_quota_reached` or `team_spend_limit_reached` with `resets_at`.
## Credits
Credits pay for API calls, at the price of the model and effort each call ran on; Agent API runs also pay for computer time, actions, browser time and storage writes ([Rates](/billing/rates)).
- **Free credit:** $5, once per account.
- **Top up any amount** from **$1 to $800** per purchase in the Console under **Billing › Credits**. Every $1 adds $1 of credits; they land on your account within seconds and don't expire. A purchase above $800 isn't credited and is refunded.
- **The Model API and the Agent API** work on every plan, Free included, as long as you have credits.
## Watching usage
- Console **Billing**: current plan, window, weekly or monthly usage (% used and reset time), Code Buckets storage used, API credits, invoices and history.
- `GET /v1/account` returns your credit balance and the last 30 days of usage ([reference](/api-reference/account/get)).
- In Line CLI, `/cost` and `/usage`; on Telegram, `/usage`.
## Running out
When your credits reach zero, API calls answer **HTTP 402** `out_of_credits`. A run that runs out midway stops with `status: "failed"` and `error.code: "out_of_credits"`. App usage isn't affected by credits; it follows your plan's limits.
---
Source: https://developers.clatterlabs.com/billing/rates
# Rates
> Every price, in one table. The same rates apply to the Agent API, Line CLI and Cosmos Agent.
Rates version **2026-10-27**. Prices in US dollars.
## SuperCosmos 1.1 tokens
| Tier | Model id | Input / 1M tokens | Output / 1M tokens |
| --- | --- | --- | --- |
| Flash | `supercosmos-flash` | $1.60 | $3.40 |
| Max | `supercosmos-max` | $1.80 | $3.80 |
| Heavy | `supercosmos-heavy` | $2.00 | $4.40 |
**Long-context input above 262K tokens: 1.5×** (SuperCosmos): a request whose prompt is over 262K tokens bills its whole input at 1.5× the rate above.
Input covers prompt and context tokens. Output includes reasoning tokens.
Line Code was retired on Nov 1, 2026 ([details](/models/line-code-retired)).
## Cloud computer
| Item | Unit | Price | Notes |
| --- | --- | --- | --- |
| Cloud computer time | minute | $0.006 | Time running commands and file work |
| Edits and tool actions | action | $0.0005 | Each file edit, command, web search or tool call |
| Cloud browser | minute | $0.005 | Navigation, clicks and typing |
| Cloud storage writes | GB written | $0.10 | Files and outputs written to the computer and run results |
## Which tier is billed
| Product | Tier billed |
| --- | --- |
| Agent API | The run's `tier`; `auto` bills as Flash |
| Line CLI | The tier of the model that answered (for `auto`, the routed tier) |
| Model API | The model id you called (each effort is its own id) |
| Cosmos Agent | The tier named for the call, otherwise inferred from how deeply it thinks |
## Example
A run on Max that reads 9,696 input tokens and writes 38 output tokens costs `9696 × $1.80/1M + 38 × $3.80/1M ≈ $0.0176` for tokens, plus any computer time and actions it used.
---
Source: https://developers.clatterlabs.com/platform/cloud-ide
# Cloud IDE
> A browser-based, full-stack development environment by Clatter Labs, with the Radar AI agent built into the terminal.
editor.clatterlabs.com
Cloud IDE by **Clatter Labs** is a browser-based, full-stack development environment for creating, editing, running, and testing applications without configuring a local development toolchain.
This guide covers project management, the editor, file operations, Git connectors, runtimes, the terminal, collaboration, and the **Radar AI agent**, including its operational limits.
## 1. Overview
Cloud IDE brings the core development workflow into a single workspace:
- **Isolated workspaces:** Each project has an independent workspace and its own file system.
- **Integrated execution:** Install dependencies and run development servers directly from the terminal.
- **Live Preview:** View running web applications inside the editor.
- **File synchronization and periodic saving:** Keep workspace files up to date as you work.
- **AI-assisted development:** Use Radar to inspect, create, and modify project files.
Periodic saving is not a substitute for version control. Save important changes explicitly and maintain a recoverable copy before large refactors or destructive operations.
### Quick start
1. Open [Cloud IDE](https://editor.clatterlabs.com).
2. From the dashboard, select **Deploy IDE**.
3. Choose a starter template or import a Git repository.
4. Enter a project name and open the workspace.
5. Review the project’s setup instructions and dependency files.
6. Install dependencies and start the application in the terminal.
7. Open **Live Preview** to inspect the running application.
For a Node.js project with a `dev` script, a typical workflow is:
```bash
npm install
npm run dev
```
Commands depend on the selected template or imported repository. Check `package.json` before running a script, and use the project’s intended package manager.
## 2. Dashboard and Project Management
The dashboard is the entry point for managing your projects and workspaces.
### Create a project
Select **Deploy IDE** to create a workspace. You can:
- Start from a template such as **React**, **Next.js**, **Vite**, **Node.js**, **Python**, or **Vanilla JavaScript**.
- Connect a Git repository to work from an existing codebase.
- Assign a custom project name.
### Manage existing projects
The project list displays your active workspaces, including:
- Project name.
- Last modification date.
- Actions to open or delete the project.
Before deleting a project, preserve any files you may need. Do not assume deleted workspaces can be recovered.
### Access and privacy
Workspace access is restricted to the project owner and explicitly authorized collaborators. An unauthorized user cannot open a workspace simply by obtaining its URL.
For the invitation workflow, see [Collaboration and Forking](#9-collaboration-and-forking).
## 3. IDE Workspace
The workspace combines navigation, code editing, execution, and application preview.
### Activity Bar
The Activity Bar provides access to the main workspace panels:
| Panel | Purpose |
| :--- | :--- |
| **Explorer** | Browse and manage project files and folders. |
| **Search** | Find and replace text across project files. |
| **Connectors** | Connect supported Git providers and import repositories. |
| **Settings** | Configure editor appearance, fonts, saving, and formatting behavior. |
### Central editor
The editor supports:
- **Multiple tabs** for working across several files.
- **Syntax highlighting** for common languages, including TypeScript, JavaScript, Python, HTML, CSS, JSON, Markdown, and YAML.
- **IntelliSense and autocomplete**.
- **Real-time syntax diagnostics**.
- **Multi-cursor editing** for changing multiple locations at once.
The usefulness of completions and diagnostics depends on the language and the project configuration.
### Toolbar
| Control | Function |
| :--- | :--- |
| **Save** | Save the current file or project state. |
| **Fork** | Create an independent copy of the project. |
| **Share Workspace** | Invite another developer by email. |
| **Sidebar toggle** | Show or hide the sidebar. |
| **Terminal toggle** | Show or hide the terminal panel. |
| **Live Preview toggle** | Show or hide the application preview. |
### Live Preview
Live Preview displays the application served by the workspace’s development server.
Its navigation controls let you:
- Change the application route.
- Reload the current page.
- Open the preview in a separate browser tab.
Live Preview requires a running web server. Opening the preview does not replace starting the application.
### Keyboard shortcuts
| Shortcut | Action |
| :--- | :--- |
| `Ctrl + S` / `Cmd + S` | Save the current file. |
| `Ctrl + B` / `Cmd + B` | Toggle the sidebar. |
| `Ctrl + J` / `Cmd + J` | Toggle the terminal. |
| `Ctrl + Shift + P` | Toggle Live Preview. |
| `Ctrl + F` / `Cmd + F` | Find text in the active file. |
| `Ctrl + H` / `Cmd + H` | Find and replace in the active file. |
| `Ctrl + /` / `Cmd + /` | Toggle line comments. |
Browser or operating-system shortcuts may intercept some key combinations. Use the corresponding interface control if a shortcut does not reach the editor.
## 4. File Explorer and Asset Management
### Create files and folders
Use the creation icons above the file tree, or right-click an empty area of the Explorer.
Nested paths are supported. For example, creating:
```text
src/components/Button.tsx
```
creates the file and any required parent folders.
### Rename, duplicate, or delete items
Right-click a file or folder to access:
- **Rename**
- **Duplicate**
- **Delete**
Check the selected path before deleting a folder, especially when it contains multiple components or configuration files.
### File icons
The Explorer identifies extensions and displays language- or framework-specific icons to make the project structure easier to scan.
### Global search
Open **Search** to search across project contents. Available controls include:
- Project-wide text search and replacement.
- Path exclusions.
- Case-sensitive matching.
Use the editor’s find command when you only need to search the active file.
## 5. Git Connectors and Repository Import
Connectors import source code from supported Git hosting providers.
### Supported providers
- **GitHub**
- **GitLab**
- **Bitbucket**
### Prepare access credentials
Create credentials with the minimum permissions needed to read the intended repositories.
| Provider | Credential setup | Read-access permissions |
| :--- | :--- | :--- |
| **GitHub** | Account settings → **Developer settings** → **Personal access tokens** → **Tokens (classic)** | The classic-token workflow uses `repo` for private repository access. This scope grants more than read-only access. |
| **GitLab** | User settings → **Access Tokens** | Prefer `read_repository`; the broader `api` scope may be required for repository-listing API access. |
| **Bitbucket** | Follow Bitbucket’s current credential setup instructions and the connector’s supported authentication flow. | Repository read access. |
Credential names, settings paths, and policies can change. Bitbucket’s legacy **App Passwords** workflow has been retired; do not rely on older instructions that require creating an app password. Confirm the credential type accepted by the Cloud IDE connector before proceeding.
### Import a repository
1. Open **Connectors** from the Activity Bar.
2. Select the Git provider.
3. Enter the supported access credential.
4. Select **Connect**.
5. Browse or search the available repositories. Repository lists support pagination.
6. Choose a repository and branch.
7. Select **Clone Repository**.
The importer retrieves the repository’s file tree and reconstructs it in the workspace.
### Import filtering
To reduce import size and startup time, the importer filters out large non-text files and generated or repository-internal directories such as:
```text
node_modules/
.git/
```
After import:
- Install dependencies from the project’s package manifest.
- Check that required assets are present.
- Review environment configuration before running the application.
This workflow imports source files. Because `.git` is excluded, do not assume it creates a conventional local clone with Git history and remotes. Import also does not imply automatic synchronization or push-back to the source repository.
### Credential handling
The described connector design keeps access tokens **encrypted and temporary within the current local session**, using them to communicate with the selected provider’s API rather than persisting them on external servers.
As a developer:
- Never place access tokens in source files, terminal examples, or Radar prompts.
- Use the narrowest supported permissions.
- Revoke credentials that are no longer needed.
- Check current deployment security documentation before connecting sensitive repositories.
## 6. Runtimes, Build Tools, and Development Servers
### JavaScript and TypeScript
Cloud IDE supports Node.js-based development workflows and the following package managers:
- `npm`
- `pnpm`
- `yarn`
- `bun`
The environment supports workflows built around tools such as **esbuild**, **SWC**, **Vite**, **Next.js**, and **Webpack**.
TypeScript and JSX/TSX compilation runs inside the workspace through the project’s configured toolchain; no local toolchain installation is required.
Support for a tool does not guarantee compatibility with every release, plugin, native dependency, or operating-system requirement. Check the project’s runtime and package requirements.
### Install and run a Node.js project
For an npm-based project:
```bash
npm install
npm run dev
```
Use the package manager associated with the repository’s lockfile. Avoid switching package managers unintentionally.
### Development server lifecycle
1. Run the project’s development command.
2. The server starts on an internal port.
3. Cloud IDE detects the server and routes it to **Live Preview**.
4. Saved changes are picked up by the project’s development tooling.
**Hot Module Replacement (HMR)** updates supported parts of the application without a full reload when the framework and server configuration enable it.
HMR behavior depends on the project. Some changes require a page reload or development-server restart.
### Python
Cloud IDE provides a Python environment for running scripts and installing compatible dependencies.
Run a script with the available Python command:
```bash
python script.py
```
Or:
```bash
python3 main.py
```
Projects can declare dependencies in `requirements.txt`. Where automatic dependency installation is not applied, install them explicitly using the available Python interpreter:
```bash
python3 -m pip install -r requirements.txt
```
Package compatibility depends on the runtime and any required native or system libraries.
## 7. Terminal
The integrated terminal provides interactive shell access to the workspace.
### Multiple sessions
Open multiple terminal tabs to separate tasks, for example:
- **Session 1:** Development server.
- **Session 2:** Dependency installation, tests, and build commands.
- **Session 3:** Radar.
Keeping the development server in its own session makes its logs easier to inspect.
### Maximize and restore
Use the terminal’s maximize control to expand it across the editor area. Select the control again to restore the normal layout.
This is useful for reviewing long build output or error logs.
### Terminal controls
| Command or shortcut | Action |
| :--- | :--- |
| `Ctrl + C` | Interrupt the active foreground process. |
| `Ctrl + L` | Clear the visible terminal display. |
| `clear` | Clear the visible terminal display. |
Clearing the screen does not stop a running process.
## 8. Radar AI Agent
**Radar** is an AI coding agent available inside the terminal. It can help write code, investigate errors, and perform file operations in the current project.
Radar can modify or delete files and execute commands. Review its changes and run appropriate checks before relying on the result.
### Start Radar
In a terminal session, run:
```bash
radar
```
The terminal enters Radar’s input mode:
```text
radar ›
```
Describe the task, relevant paths, and any restrictions.
For example:
```text
Read src/components/Button.tsx and fix the disabled-state styling.
Do not change other files. Explain the changes when finished.
```
### Available tools
| Tool | Capability |
| :--- | :--- |
| `read` | Inspect text-file contents. |
| `write` | Create a file or replace an existing file’s contents. |
| `delete` | Delete a file. |
| `open` | Open a file in the editor. |
| `run` | Execute commands, such as builds or dependency installation, when explicitly requested. |
A request to analyze code is different from permission to run commands. State command-execution requirements explicitly.
### Operational limits
| Limit | Behavior | Recommended approach |
| :--- | :--- | :--- |
| **Tool-loop limit** | Up to **5 consecutive tool steps per request**. | Divide complex work into small tasks and request continuation when needed. |
| **Conversation history** | Retains the latest **16 conversation entries** in active context; older entries are omitted. | Restate essential paths, constraints, and decisions during longer sessions. |
| **Binary files** | Cannot read or edit images, videos, fonts, ZIP archives, or other binary content. | Work with related source code, metadata, or asset references. |
| **Large text files** | Very large files may be truncated. The supplied specification does not define an exact byte threshold. | Target smaller files or specific components. |
| **Long-running commands** | Persistent or continuously interactive processes are unsuitable for Radar’s command tool. | Run development servers and similar processes in a normal terminal session. |
Reading a file, writing it, and running a check can consume separate steps. A five-step allowance does not guarantee five completed file edits.
### Continue a multi-step task
If Radar stops after reaching its step limit, enter a follow-up request:
```text
Continue the remaining changes. Keep the same scope and constraints.
```
Review completed work before continuing. A follow-up starts another bounded sequence; it does not remove the per-request limit.
### Exit Radar
To return to the normal shell:
```text
exit
```
Alternatively, press `Ctrl + C`.
### Recommended workflow
1. Ask Radar to inspect the relevant files.
2. Define a narrow modification scope.
3. Request the change.
4. Review the edited files.
5. Run tests or build checks.
6. Continue with the next task.
For long sessions, repeat important constraints rather than relying on older conversation history.
## 9. Collaboration and Forking
### Share a workspace
1. Select **Share Workspace** in the toolbar.
2. Enter the invited developer’s email address.
3. The system creates a secured invitation link and notifies the user.
4. The invited user opens the link and accepts the invitation.
5. The user joins the shared workspace with file synchronization.
Users who are not authorized for the project are denied access, even if they have the invitation or workspace URL.
Coordinate edits to shared files. File synchronization should not be treated as a guarantee of conflict-free simultaneous editing.
### Fork a workspace
Use **Fork** when you want an independent copy for experimentation or substantial refactoring.
1. Select **Fork**.
2. Enter a name for the new project.
3. Open the newly created workspace.
The fork contains a copy of the project files and settings and is independent of the original workspace.
Changes in the fork do not modify the original project.
## 10. Settings and Customization
Open **Settings** from the Activity Bar.
| Setting | Purpose |
| :--- | :--- |
| **Theme** | Choose dark, light, or high-contrast appearance. |
| **Editor Font Size** | Adjust the code editor’s text size. |
| **Terminal Font** | Adjust terminal typography. |
| **Tab Size** | Set indentation width, such as two or four spaces. |
| **Word Wrap** | Wrap long lines within the visible editor width. |
| **Minimap** | Show or hide the code overview beside the editor. |
Saving and formatting behavior can also be adjusted through the available settings.
Keep project formatting configuration aligned with editor preferences to avoid unnecessary formatting changes.
## 11. Troubleshooting
### Live Preview is blank or shows `Connection Refused`
1. Check the terminal where the development server should be running.
2. Look for a startup confirmation and local address, such as `http://localhost:...`.
3. If the server stopped, inspect the error and restart it using the project’s command:
```bash
npm run dev
```
4. Select **Reload** in Live Preview.
5. Confirm that the preview route exists in the application.
A blank page with a running server may indicate an application error rather than a connection problem. Review server output and browser error messages.
### Dependency installation fails
1. Read the first meaningful error in the installation output.
2. Check `package.json`, the lockfile, and the required runtime version.
3. Use the package manager expected by the project.
4. Resolve incompatible dependency versions where possible.
For an npm peer-dependency conflict, a temporary workaround may be:
```bash
npm install --legacy-peer-deps
```
This option bypasses peer-dependency resolution constraints. It can install an incompatible dependency combination; it is not a general solution for installation failures.
### A repository is missing from Connectors
Check that:
- The credential has not expired or been revoked.
- It belongs to an account with access to the repository.
- Its permissions allow the required repository and API operations.
- Any provider-side organization approval requirements have been satisfied.
- You have checked additional result pages or searched for the repository name.
### Imported files or dependencies are missing
The importer filters generated directories and large non-text content.
- Reinstall dependencies from the project manifest.
- Check required assets individually.
- Do not expect `.git` history or `node_modules` to be included.
### Radar stops during a complex task
Radar may have reached its **five-step tool limit**.
1. Review the changes already made.
2. Ask it to continue.
3. Restate important requirements if the conversation has become long.
4. Split the remaining work into smaller tasks.
### Radar cannot process a file
- Confirm that the file is text, not binary.
- Check whether the file is unusually large.
- Direct Radar to a smaller component or more specific file.
- Avoid assuming that truncated content has been fully inspected.
### A development server blocks the Radar workflow
Run the server in a separate, normal terminal session. Use Radar for bounded operations such as inspecting files, applying changes, and executing explicitly requested build or test commands.
---
## Multi-page series generator
Turn a long documentation guide into a structured series of Markdown pages. This workflow uses **Cloud IDE** and **Radar** to plan the series, draft pages in small batches, and review navigation and technical accuracy.
The example below organizes the **Cloud IDE Developer Documentation** into focused pages for setup, development, collaboration, and troubleshooting.
This is a documentation-generation workflow using Radar’s existing file tools—not a dedicated generator command or publishing feature. Site navigation and rendering depend on your documentation framework.
## Before You Begin
You need:
- A Cloud IDE workspace.
- The source documentation saved as a text or Markdown file.
- A destination folder for the generated pages.
- Any existing documentation conventions, including filenames, links, and front matter.
Open [Cloud IDE](https://editor.clatterlabs.com), then open or create a project.
Before generating files:
1. Save your current work.
2. Preserve a recoverable copy or use **Fork** to create an independent workspace.
3. Check the destination folder for files that must not be overwritten.
4. Remove credentials and other sensitive information from the source.
Radar can create, replace, and delete files. Specify the permitted output paths and review each batch before continuing.
## Plan the Series
### Define the audience and page boundaries
Organize pages around reader tasks rather than splitting the source into equally sized sections.
For the Cloud IDE guide, use this structure:
| Page | File | Coverage |
| :--- | :--- | :--- |
| Overview and quick start | `index.md` | Product overview, prerequisites, first application |
| Projects and workspace | `projects-and-workspace.md` | Dashboard, project access, editor, toolbar, shortcuts |
| Files and search | `files-and-search.md` | File operations, assets, search and replacement |
| Repository imports | `repository-imports.md` | Providers, credentials, import steps and filtering |
| Running applications | `running-applications.md` | Runtimes, dependencies, development servers, Live Preview |
| Terminal | `terminal.md` | Sessions, controls, maximizing and restoring |
| Radar AI agent | `radar.md` | Tools, prompts, operational limits, review workflow |
| Collaboration and forks | `collaboration-and-forks.md` | Invitations, access restrictions, independent copies |
| Settings | `settings.md` | Appearance, typography, saving and formatting |
| Troubleshooting | `troubleshooting.md` | Common failures and recovery steps |
Keep warnings beside the procedures they qualify. For example, repository import limitations belong on the repository page, not only in troubleshooting.
### Create an outline first
Start Radar in the terminal:
```bash
radar
```
Ask for an outline before requesting page files. Replace the example paths with your own:
```text
Read docs/source/cloud-ide.md.
Propose a multi-page documentation series for developers.
For each page, provide a title, filename, purpose, source sections,
and related pages.
Preserve all technical limits, security warnings, and compatibility notes.
Do not invent features, commands, settings, or product guarantees.
Identify unclear claims for review rather than resolving them by guessing.
Do not modify files or run commands yet.
```
Review the outline for missing topics, duplicated instructions, and pages that are too broad.
Once approved, save it as a working plan, such as `docs/series-plan.md`.
## Generate the Pages
### Use a consistent page structure
Each page should include:
- **Purpose:** What the reader can accomplish.
- **Prerequisites:** Required access, files, or running services.
- **Instructions:** Task-oriented steps and relevant examples.
- **Limitations:** Warnings and constraints from the source.
- **Related pages:** Links to the next task or supporting information.
A minimal page pattern is:
```markdown
## Page Title
Explain the page’s purpose.
### Before you begin
- Required access or setup.
### Complete the task
1. Perform the first action.
2. Verify the result.
Include relevant limitations from the source.
### Related pages
- [Series overview](index.md)
- [Next topic](next-topic.md)
```
Use your documentation framework’s established conventions if they differ.
### Generate one page at a time
Radar allows up to **five consecutive tool steps per request**. Reading source material, writing a page, and running a check can each consume separate steps.
Example request:
```text
Read docs/series-plan.md and the relevant sections of
docs/source/cloud-ide.md.
Create only docs/cloud-ide/repository-imports.md.
Do not overwrite an existing file; report it if the path already exists.
Cover supported providers, credential preparation, import steps,
filtering, and credential-handling cautions.
Preserve the distinction between importing source files and creating
a conventional Git clone. Do not imply automatic synchronization
or push-back to the repository.
Use GitHub-flavored Markdown and relative links from the approved plan.
Do not modify other files or run commands.
Report anything left incomplete.
```
Review the result before requesting the next page.
Radar retains the latest **16 conversation entries** in active context. Repeat essential paths and constraints in later requests rather than relying on earlier messages.
If Radar stops, inspect the files before continuing:
```text
Continue only the unfinished repository-imports page.
Keep the same scope and constraints.
Do not recreate completed content or modify other files.
```
## Add Navigation
Use the overview page as the series entry point. Include a short description and a linked list of all pages.
Add relevant cross-links where readers need them:
- Link **Live Preview** instructions to application startup.
- Link repository import completion to dependency installation.
- Link Radar’s command limitations to terminal sessions.
- Link troubleshooting entries back to their main procedures.
Relative Markdown links do not automatically configure a documentation site’s sidebar or routes. Update site configuration only according to the framework already used by the project.
## Validate the Series
### Check technical accuracy
Compare each page with the source. Confirm that it preserves these important distinctions:
- Live Preview requires a running web server.
- Repository import excludes `.git` and does not imply automatic push-back.
- Periodic saving is not version control.
- Radar’s tool-step allowance is not a file-count allowance.
- Radar cannot read or edit binary files.
- Persistent development servers should run in a normal terminal session.
- Workspace synchronization does not guarantee conflict-free editing.
- Forks are independent of the original workspace.
### Check structure and links
Before publishing, verify that:
- Every planned page exists.
- Every relative link resolves to the intended page or heading.
- No source topic or important warning was dropped.
- Examples use the correct project commands and package manager.
- Generated pages contain no invented interface controls or guarantees.
- Shared instructions are consistent across pages.
If the project has documentation checks, inspect its configuration and run the documented commands. Ask Radar explicitly before using its command tool.
## Troubleshooting
| Issue | Recommended action |
| :--- | :--- |
| Radar stops partway through generation | Review completed work, then request a smaller continuation. |
| Important constraints disappear in later pages | Restate them and reference the saved series plan. |
| Source content is too large to inspect fully | Split it into smaller text files and process relevant sections separately. |
| Pages repeat the same procedures | Keep one authoritative procedure and link to it. |
| Links fail in the rendered site | Check filenames, heading anchors, and framework routing conventions. |
| Generated claims are unsupported | Remove or flag them, then compare the page with the source again. |
The series is ready for publication when its pages are complete, its links work, and its technical claims remain faithful to the source.
---
Source: https://developers.clatterlabs.com/platform/cla-wtf
# cla.wtf
> Clatter Labs' official short-link and dynamic-link domain.
**cla.wtf** is the URL shortening and dynamic linking domain owned and operated by **Clatter Labs**. It gives every Clatter Labs link a short, branded, secure form.
Open cla.wtf
## What it does
- **Dynamic linking**: smart links that send people to the right place (web, iOS or Android) for their device.
- **URL shortening**: long Clatter Labs resource URLs become short, shareable links.
- **Security**: links are managed by Clatter Labs and protected against tampering.
- **Fast routing**: global infrastructure keeps redirects quick.
## Where you'll see it
1. **Direct links** in Clatter Labs docs and messages, for example [cla.wtf/help](https://cla.wtf/help).
2. **App deep links** that open a Clatter Labs app on a specific page or tool.
3. **Secure sharing** of private assets or workspace files.
All `cla.wtf` links are managed directly by Clatter Labs. A link on this domain is an official Clatter Labs link.
## Questions
If a `cla.wtf` link doesn't resolve, or you have a question about one, visit the [Help Center](https://help.clatterlabs.com).
---
Source: https://developers.clatterlabs.com/platform/status
# Service status
> Live health, incidents and maintenance for every Clatter Labs service.
The Clatter Labs status page gives real-time transparency into the health of our infrastructure and services: current status, ongoing incidents, history and scheduled maintenance.
status.clatterlabs.com
## Key features
- **Real-time monitoring** of Clatter Labs core services, including API endpoints, web apps and backend processing.
- **Incident transparency**: detailed logs of active disruptions, with investigation steps, causes and progress to resolution.
- **Uptime history**: performance over the past 30 to 90 days.
- **Maintenance notices** in advance, so you can plan around them.
## Stay updated
On the [status page](https://status.clatterlabs.com), choose **Subscribe** and enter your email to get alerts when an incident is created, updated or resolved.
Point a feed reader or an integration at `https://status.clatterlabs.com/rss.xml`.
Past incidents and uptime are archived at `https://status.clatterlabs.com/history`, useful for audits and reliability reviews.
## Service states
| State | Meaning |
| :--- | :--- |
| **Operational** | Working as expected, no known issues |
| **Degraded performance** | Working, but you may see higher latency |
| **Partial outage** | Some features or components are unavailable |
| **Major outage** | The service is unavailable or critical functions are lost |
If the API misbehaves but the status page shows **Operational**, check your network, your API key and your Account ID header before contacting support. The [Errors](/agent/errors) page lists every API error code.
## Get help
If you hit a problem that isn't on the status page, the [Help Center](https://help.clatterlabs.com) has answers for every Clatter Labs product.
---
Source: https://developers.clatterlabs.com/platform/support
# Help Center
> Answers and guides for every Clatter Labs product.
The **Clatter Labs Help Center** has answers and step-by-step guides for every Clatter Labs product: your account, billing and plans, the Console, SuperCosmos, the Model API, the Agent API, Line CLI, Code Buckets, Cosmos Agent on Telegram and more.
help.clatterlabs.com
## Find your way around
- **Search**: type your question in plain words.
- **Products**: each product has its own page, with articles grouped by topic.
- **Popular**: the most-asked questions are on the home page.
## Still need help?
- Email **support@clatterlabs.com** or **team@clatterlabs.xyz**.
- Questions about our infrastructure, or permanent deletion of your data (your whole account or one service): **infrastructure@clatterlabs.xyz**.
Include your **Account ID** (`CL-…`) and, for API errors, the `X-Request-Id` of the request.
---
Source: https://developers.clatterlabs.com/policies/abuse
# Abuse policy
> Insulting or cursing at the assistant earns a warning, then a 24-hour suspension. API key owners are responsible for their end users' text.
Clatter Labs models are here to help you build. Insulting or cursing at the assistant isn't allowed on any Clatter Labs product. This page explains what counts, what happens, and what developers who send their users' text through our APIs need to do.
## Where it applies
Line CLI, the Model API, the Agent API, the Console Playground and Cosmos Agent (Telegram included). A suspension covers all of them at once. The [Help Center](https://help.clatterlabs.com) always stays reachable.
## What counts
A message counts when the person writing it insults or curses **at the assistant**. These don't count:
- Swearing at a bug, a failing build, a tool or a third party ("this test is driving me crazy")
- Quoted text: code, logs, pasted errors, string literals, quotes, or text you say someone else wrote
- Asking about a word, translating it, or building a filter for it
Only the newest message a person wrote is checked, never tool output, system prompts or the model's own replies.
## What happens
| Strike | What happens |
| --- | --- |
| First in 30 days | **Warning.** The request is answered normally and carries a warning notice. |
| Second within 30 days | **24-hour suspension.** Your account is paused on every Clatter Labs product for 24 hours, starting with that request. |
When the 24 hours end, your account works again on its own. Your credits, plan, keys and data are not touched.
## Model API and Agent API: the key owner is responsible
An API key acts for the account that owns it. If your app sends its **end users' text** to the Model API or the Agent API, that text counts against **your** account, the key owner's, exactly as if you had written it. One abusive end user can trigger a warning and then a suspension of your whole account.
Filter or moderate end-user input before you send it, and act on the warning header (below) as soon as you see it: for example, by blocking the end user who sent that message.
## How you see it in the API
**Warning.** A request that earned a warning succeeds normally and carries two response headers:
| Header | Value |
| --- | --- |
| `x-clatter-notice` | `abuse_warning` |
| `x-clatter-notice-text` | The warning text, URL-encoded |
Both headers are readable from the browser (exposed for CORS). Log them, and alert yourself when they appear.
**Suspension.** While your account is paused, every call answers `403` with code `account_suspended`, a `Retry-After` header (seconds until it lifts), and the time it lifts in `resets_at`:
```json
{
"error": {
"message": "Your Clatter Labs account is paused until 2026-11-03 14:05 UTC under the abuse policy: ...",
"type": "permission_error",
"code": "account_suspended",
"resets_at": "2026-11-03T14:05:00.000Z",
"appeal_url": "https://support.clatterlabs.com",
"policy_url": "https://developers.clatterlabs.com/policies/abuse"
}
}
```
Don't retry before `resets_at`: retries fail the same way. In Line CLI and Cosmos Agent the same warning and pause appear as a message.
## What we keep
For each strike we keep a short, redacted excerpt of the message (no code and no links) so an appeal can be reviewed. Excerpts are erased after 30 days.
## Appeals
If you think a strike or a suspension was a mistake, follow [Appeal a suspension](https://help.clatterlabs.com/security-privacy/suspension/appeal-a-suspension) with your Account ID and the time of the request. If the appeal is accepted, the suspension is lifted early.
---
Source: https://developers.clatterlabs.com/api-reference/introduction
# API reference
> The Clatter Labs Agent API runs Cosmos Agent, with its tools and cloud computer, from any language over HTTPS.
## Base URL
```text
https://api.agent.clatterlabs.xyz
```
All requests use HTTPS. Request and response bodies are JSON, except the [event stream](/api-reference/runs/events) (`text/event-stream`).
## Authentication
Send your API key and your Account ID on every request. See [Authentication](/api-reference/authentication).
```http
Authorization: Bearer clsk_...
X-Clatter-Account: CL-XXXXXXXX
```
## Endpoints
| Method | Path | Permission | |
| --- | --- | --- | --- |
| `GET` | `/agent-config` | none | [Describe the API](/api-reference/agent-config) |
| `POST` | `/v1/runs` | `runs:write` | [Create a run](/api-reference/runs/create) |
| `GET` | `/v1/runs` | `runs:read` | [List runs](/api-reference/runs/list) |
| `GET` | `/v1/runs/{id}` | `runs:read` | [Get a run](/api-reference/runs/get) |
| `GET` | `/v1/runs/{id}/events` | `runs:read` | [Stream run events](/api-reference/runs/events) |
| `POST` | `/v1/runs/{id}/cancel` | `runs:write` | [Cancel a run](/api-reference/runs/cancel) |
| `GET` | `/v1/account` | `account:read` | [Get account](/api-reference/account/get) |
## Versioning
The API version is a date, returned by `/agent-config` as `version` (currently `2026-10-27`). Changes that could break your code get a new version and a [changelog](/changelog) entry.
## Try it
Every endpoint page has a **Try it** button. It sends real requests from your browser straight to the API; your key stays in that browser tab and never passes through this site.
First run in five minutes.Codes and what to do.
---
Source: https://developers.clatterlabs.com/api-reference/authentication
# Authentication
> API keys plus your Account ID on every request.
The Agent API uses **API keys** created in the [Console](https://console.clatterlabs.com/api-keys). Each request carries two headers:
`Bearer clsk_...`: your API key.
The Account ID that owns the key, like `CL-7K2M9QXA` (Console › Settings). Matching is case-insensitive.
```bash
curl https://api.agent.clatterlabs.xyz/agent-config \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Why two headers
A key alone isn't enough: the request must also name the account that owns it. A key that leaks without its Account ID can't be used, and a key sent with someone else's Account ID is refused.
| Situation | Response |
| --- | --- |
| No `X-Clatter-Account` | `401 missing_account_id` |
| Account ID doesn't own the key | `401 account_mismatch` |
| Key wrong or revoked | `401 invalid_api_key` |
| Key lacks the permission | `403 insufficient_scope` |
## Permissions
| Permission | Endpoints |
| --- | --- |
| `runs:write` | `POST /v1/runs`, `POST /v1/runs/{id}/cancel` |
| `runs:read` | `GET /v1/runs`, `GET /v1/runs/{id}`, `GET /v1/runs/{id}/events` |
| `account:read` | `GET /v1/account` |
`GET /agent-config` needs no key; with one it also describes the key.
## CORS
The API allows cross-origin requests, which is what makes **Try it** work. That doesn't make it safe to put keys in front-end code: call the API from your server.
---
Source: https://developers.clatterlabs.com/api-reference/errors
# Errors
> Error format, status codes and error codes.
Every error is JSON with a `code` you can branch on and a `message` for people:
```json
{ "error": { "code": "invalid_api_key", "message": "This API key is invalid or was revoked." } }
```
| Status | Codes |
| --- | --- |
| `400` | `bad_request` |
| `401` | `invalid_api_key`, `missing_account_id`, `account_mismatch` |
| `402` | `out_of_credits` |
| `403` | `insufficient_scope`, `early_access`, `no_cloud_account`, `account_suspended` (with `resets_at` and `Retry-After`; see the [Abuse policy](/policies/abuse)) |
| `404` | `not_found` |
| `405` | `method_not_allowed` |
| `410` | `model_retired` (Model API: a retired model id, see [Line Code retirement](/models/line-code-retired)) |
| `413` | `too_large` |
| `429` | `rate_limited`, `too_many_runs`, `window_limit_reached`, `weekly_limit_reached`, `monthly_limit_reached` (app usage; with `resets_at` and `Retry-After`) |
| `502` | `upstream` |
| `503` | `unavailable` |
The [Errors guide](/agent/errors) explains each code and what to do about it.
---
Source: https://developers.clatterlabs.com/api-reference/rate-limits
# Rate limits
> Per-key requests per minute, concurrent runs, and the headers that tell you where you stand.
## Requests per minute
Each API key has its own limit, chosen when you create it: **10, 30 (default), 60 or 120** requests per minute.
Keyed responses include:
| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | The key's requests per minute |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `Retry-After` | On `429`: seconds to wait |
```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 30
{ "error": { "code": "rate_limited", "message": "..." } }
```
## Runs in progress
An account can have **5** runs queued or running at once. A sixth answers `429 too_many_runs`. Wait for one to finish or cancel one.
## Tips
- An open [event stream](/api-reference/runs/events) counts once, when you open it, however long it runs.
- Back off on `429` using `Retry-After`; don't retry in a tight loop.
- Need more? Use separate keys per service, or create a key with a higher limit.
---
Source: https://developers.clatterlabs.com/api-reference/agent-config
# Describe the API
> The API's version, endpoints, the agent's tools and limits, and with a key, your key and balance.
`GET https://api.agent.clatterlabs.xyz/agent-config`
Describes the API: version, endpoints, the agent's tools and limits. Works without a key; with a key and your Account ID it also returns the key's permissions, rate limit and your credit balance.
## Authorizations
- `Authorization` (string): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string): 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`.
## Response
- `version` (string): API version date.
- `agent` (object): The agent: name, model family, tiers, tools and limits.
- `endpoints` (object[]): Every endpoint with its method, path and required scope.
- `key` (object): Only when a key is sent: its id, name, scopes and `rate_limit_rpm`.
- `account` (object): Only when a key is sent: `cloud_id`, `balance_usd`, `unlimited`, `can_run`.
## Example request
```bash
curl "https://api.agent.clatterlabs.xyz/agent-config" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Example response
```json
{
"object": "agent_config",
"service": "Clatter Labs Agent API",
"by": "Clatter Labs",
"version": "2026-10-27",
"base_url": "https://api.agent.clatterlabs.xyz",
"auth": {
"type": "bearer",
"header": "Authorization: Bearer clsk_...",
"account_header": "X-Clatter-Account: CL-...",
"scopes": [
"runs:write",
"runs:read",
"account:read"
]
},
"agent": {
"name": "Cosmos",
"product": "Cosmos Agent",
"model": "SuperCosmos by Clatter Labs",
"tiers": [
"auto",
"flash",
"max",
"heavy"
],
"default_tier": "auto",
"limits": {
"max_steps_per_run": 150,
"max_input_chars": 20000,
"max_metadata_bytes": 2048,
"max_runs_in_progress": 5
}
},
"key": {
"id": "key_7f3a…",
"name": "CI bot",
"scopes": [
"runs:write",
"runs:read"
],
"rate_limit_rpm": 30
},
"account": {
"cloud_id": "CL-7K2M9QXA",
"balance_usd": 19.97,
"unlimited": false,
"can_run": true
}
}
```
Call it without headers to discover the API, or with your key and Account ID to check them and see your balance before starting runs. Without a key the response is cacheable for 5 minutes.
---
Source: https://developers.clatterlabs.com/api-reference/runs/create
# Create a run
> Start Cosmos Agent on a task.
`POST https://api.agent.clatterlabs.xyz/v1/runs` (key permission: `runs:write`)
Starts Cosmos on its cloud computer with your instructions. Answers `201` right away with the run; follow it with the events stream or poll it.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string, required): 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`.
## Body
- `input` (string, required): What Cosmos should do, in plain language. Up to 20,000 characters.
- `title` (string): A short name for the run (up to 80 characters). Defaults to the first line of `input`.
- `tier` (enum, default auto): The SuperCosmos tier to run on. `auto` lets Cosmos route each step; tokens are billed at the tier each call actually runs on (an `auto` run bills as Flash). Options: auto, flash, max, heavy.
- `metadata` (object): Your own key/value data, up to 2 KB. Returned as-is on the run.
## Response
- `id` (string): The run id (UUID).
- `object` (string): Always `run`.
- `status` (enum): `queued`, `running`, `completed`, `failed` or `cancelled`.
- `title` (string): The run's title.
- `input` (string): Your instructions (first 4,000 characters).
- `output` (string | null): Cosmos's final answer once `completed`, otherwise `null`.
- `error` (object | null): When `failed`: `{ code, message }`, code `out_of_credits` or `run_failed`.
- `files` (object[]): Files the run saved as outputs: `{ name, bytes }`, plus `content` with `?include=files`.
- `steps` (integer): How many steps the agent took.
- `tier` (string): The tier you asked for: `auto`, `flash`, `max` or `heavy`.
- `usage` (object): `{ tokens }` used by the run.
- `metadata` (object | null): Your `metadata`, returned as-is.
- `key_id` (string): The API key that created the run.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl -X POST "https://api.agent.clatterlabs.xyz/v1/runs" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"input": "Write hello.py that prints the date, run it, and tell me the output.",
"title": "Hello from the API",
"tier": "auto",
"metadata": {
"ticket": "OPS-112"
}
}'
```
## Example response
```json
{
"id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
"object": "run",
"status": "running",
"title": "Hello from the API",
"input": "Write hello.py that prints the date, run it, and tell me the output.",
"output": null,
"error": null,
"files": [],
"steps": 0,
"tier": "auto",
"usage": {
"tokens": 0
},
"metadata": {
"ticket": "OPS-112"
},
"key_id": "key_7f3a…",
"created_at": "2026-10-27T18:40:02.114Z",
"updated_at": "2026-10-27T18:40:02.114Z"
}
```
Write `input` like a ticket: the goal, the limits, and what "done" looks like. See [Your first real run](/agent/first-run).
---
Source: https://developers.clatterlabs.com/api-reference/runs/list
# List runs
> Your API runs, newest first.
`GET https://api.agent.clatterlabs.xyz/v1/runs` (key permission: `runs:read`)
Your API runs, newest first.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string, required): 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`.
## Query parameters
- `limit` (integer, default 20): How many runs to return, 1 to 100.
- `before` (string): A `created_at` timestamp: return runs created before it (for paging).
## Response
- `object` (string): Always `list`.
- `data` (Run[]): Runs, newest first. See [Get a run](/api-reference/runs/get) for the fields.
- `has_more` (boolean): `true` when older runs exist. Pass the last run's `created_at` as `before` to get them.
## Example request
```bash
curl "https://api.agent.clatterlabs.xyz/v1/runs?limit=10" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Example response
```json
{
"object": "list",
"data": [
{
"id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
"object": "run",
"status": "completed",
"title": "Hello from the API",
"input": "Write hello.py that prints the date, run it, and tell me the output.",
"output": "I wrote hello.py and ran it. It printed: 2026-10-27 21:40:12",
"error": null,
"files": [
{
"name": "hello.py",
"bytes": 61
}
],
"steps": 4,
"tier": "auto",
"usage": {
"tokens": 18342
},
"metadata": {
"ticket": "OPS-112"
},
"key_id": "key_7f3a…",
"created_at": "2026-10-27T18:40:02.114Z",
"updated_at": "2026-10-27T18:40:31.870Z"
}
],
"has_more": false
}
```
Only runs started through the Agent API are listed.
---
Source: https://developers.clatterlabs.com/api-reference/runs/get
# Get a run
> Status, output, files and usage of one run.
`GET https://api.agent.clatterlabs.xyz/v1/runs/{id}` (key permission: `runs:read`)
The run's status, final output, the files it saved and its usage.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string, required): 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
- `id` (string, required): The run id (a UUID).
## Query parameters
- `include` (enum): `files` adds each saved file's `content`. Options: files.
## Response
- `id` (string): The run id (UUID).
- `object` (string): Always `run`.
- `status` (enum): `queued`, `running`, `completed`, `failed` or `cancelled`.
- `title` (string): The run's title.
- `input` (string): Your instructions (first 4,000 characters).
- `output` (string | null): Cosmos's final answer once `completed`, otherwise `null`.
- `error` (object | null): When `failed`: `{ code, message }`, code `out_of_credits` or `run_failed`.
- `files` (object[]): Files the run saved as outputs: `{ name, bytes }`, plus `content` with `?include=files`.
- `steps` (integer): How many steps the agent took.
- `tier` (string): The tier you asked for: `auto`, `flash`, `max` or `heavy`.
- `usage` (object): `{ tokens }` used by the run.
- `metadata` (object | null): Your `metadata`, returned as-is.
- `key_id` (string): The API key that created the run.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Example response
```json
{
"id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
"object": "run",
"status": "completed",
"title": "Hello from the API",
"input": "Write hello.py that prints the date, run it, and tell me the output.",
"output": "I wrote hello.py and ran it. It printed: 2026-10-27 21:40:12",
"error": null,
"files": [
{
"name": "hello.py",
"bytes": 61
}
],
"steps": 4,
"tier": "auto",
"usage": {
"tokens": 18342
},
"metadata": {
"ticket": "OPS-112"
},
"key_id": "key_7f3a…",
"created_at": "2026-10-27T18:40:02.114Z",
"updated_at": "2026-10-27T18:40:31.870Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/runs/events
# Stream run events
> Server-sent events while a run works.
`GET https://api.agent.clatterlabs.xyz/v1/runs/{id}/events` (key permission: `runs:read`)
Server-sent events while the run works: `status` when it changes, one `step` per agent message or tool call, then `done` with the final run. One connection lasts up to 10 minutes; reconnect with `?after=N` to continue.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string, required): 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
- `id` (string, required): The run id.
## Query parameters
- `after` (integer, default 0): Skip the first N steps (the number of `step` events you already have).
## Response
- `event: status` ({ status }): The run's status changed: `queued`, `running`, `completed`, `failed` or `cancelled`.
- `event: step` (Step): One agent step.
- `event: done` (Run): The finished run, same shape as [Get a run](/api-reference/runs/get).
- `event: timeout` ({ message, after }): The 10-minute connection limit was reached; the run continues. Reconnect with `?after=` set to `after`.
- `event: error` ({ code, message }): The stream stopped (for example the key was revoked). Reconnect with `?after=N`.
## Example request
```bash
curl -N "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/events" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Example response
```text
event: status
data: {"status":"running"}
event: step
data: {"index":0,"type":"message","text":"I'll write hello.py and run it."}
event: step
data: {"index":1,"type":"tool","name":"computer_files","ok":true,"args":"{\"path\":\"hello.py\"}","output":"wrote 61 bytes"}
event: done
data: {"id":"4f0c2a6e-…","object":"run","status":"completed","output":"…"}
```
See [Streaming events](/agent/streaming) for a full client with reconnection.
---
Source: https://developers.clatterlabs.com/api-reference/runs/cancel
# Cancel a run
> Stop a queued or running run.
`POST https://api.agent.clatterlabs.xyz/v1/runs/{id}/cancel` (key permission: `runs:write`)
Stops a queued or running run at its next step, along with any sub-agents it started.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string, required): 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
- `id` (string, required): The run id.
## Response
- `id` (string): The run id (UUID).
- `object` (string): Always `run`.
- `status` (enum): `queued`, `running`, `completed`, `failed` or `cancelled`.
- `title` (string): The run's title.
- `input` (string): Your instructions (first 4,000 characters).
- `output` (string | null): Cosmos's final answer once `completed`, otherwise `null`.
- `error` (object | null): When `failed`: `{ code, message }`, code `out_of_credits` or `run_failed`.
- `files` (object[]): Files the run saved as outputs: `{ name, bytes }`, plus `content` with `?include=files`.
- `steps` (integer): How many steps the agent took.
- `tier` (string): The tier you asked for: `auto`, `flash`, `max` or `heavy`.
- `usage` (object): `{ tokens }` used by the run.
- `metadata` (object | null): Your `metadata`, returned as-is.
- `key_id` (string): The API key that created the run.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl -X POST "https://api.agent.clatterlabs.xyz/v1/runs/RUN_ID/cancel" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Example response
```json
{
"id": "4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10",
"object": "run",
"status": "cancelled",
"title": "Hello from the API",
"input": "Write hello.py that prints the date, run it, and tell me the output.",
"output": null,
"error": null,
"files": [
{
"name": "hello.py",
"bytes": 61
}
],
"steps": 4,
"tier": "auto",
"usage": {
"tokens": 18342
},
"metadata": {
"ticket": "OPS-112"
},
"key_id": "key_7f3a…",
"created_at": "2026-10-27T18:40:02.114Z",
"updated_at": "2026-10-27T18:40:31.870Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/account/get
# Get account
> Credit balance and 30 days of usage.
`GET https://api.agent.clatterlabs.xyz/v1/account` (key permission: `account:read`)
Your credit balance and the last 30 days of usage across Line CLI, Cosmos Agent and the Agent API.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys).
- `X-Clatter-Account` (string, required): 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`.
## Response
- `cloud_id` (string): Your Account ID.
- `plan` (string): `Free tier`, or `Clatter Labs team (unlimited)`.
- `balance_usd` (number): Credits left, in US dollars.
- `granted_usd / spent_usd` (number): Credits granted so far and credits used.
- `metered_usd` (number): List price of everything metered (equals `spent_usd` unless the account is a team account).
- `out_of_credits` (boolean): `true` when metered products answer `402 out_of_credits`.
- `usage_30d` (object): Totals for the last 30 days: events, tokens in/out, computer and browser milliseconds, actions, storage bytes, cost.
- `by_product_30d` (object[]): The same, split by product (`line`, `agent`, `api`).
## Example request
```bash
curl "https://api.agent.clatterlabs.xyz/v1/account" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Example response
```json
{
"object": "account",
"cloud_id": "CL-7K2M9QXA",
"team": false,
"plan": "Free",
"balance_usd": 4.94,
"granted_usd": 5,
"spent_usd": 0.06,
"metered_usd": 0.06,
"out_of_credits": false,
"usage_30d": {
"events": 42,
"tokens_in": 391204,
"tokens_out": 18450,
"compute_ms": 912000,
"actions": 37,
"browser_ms": 0,
"storage_bytes": 20480,
"cost_usd": 0.061,
"charged_usd": 0.061
},
"by_product_30d": [
{
"product": "api",
"label": "Agent API",
"events": 12,
"tokens": 210331,
"cost_usd": 0.031,
"charged_usd": 0.031
},
{
"product": "line",
"label": "Line CLI",
"events": 30,
"tokens": 199323,
"cost_usd": 0.03,
"charged_usd": 0.03
}
]
}
```
---
Source: https://developers.clatterlabs.com/api-reference/model-api/introduction
# Model API
> Base URL, authentication, model ids, errors and rate limits of the OpenAI-compatible Model API.
The Model API is OpenAI-compatible. Point an OpenAI SDK at the base URL, send your key and Account ID, and use the model ids below.
```text
https://api.gateway.clatterlabs.xyz/v1
```
| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/models` | The model ids with prices (no key needed) |
| `GET` | `/v1/models/{id}` | One model |
| `POST` | `/v1/chat/completions` | A chat completion, streamed or not, with tools and `usage` |
## Authentication
`Bearer clsk_...`: an API key with the **models:invoke** permission ([Console › API keys](https://console.clatterlabs.com/api-keys), preset **Model API**).
The Account ID that owns the key, like `CL-7K2M9QXA` (Console › Settings). With an OpenAI SDK, send it as a default header.
## Models
| Model id | Model | Effort | Input / 1M tokens | Output / 1M tokens |
| --- | --- | --- | --- | --- |
| `supercosmos-flash` | SuperCosmos | Flash | $1.60 | $3.40 |
| `supercosmos-max` | SuperCosmos | Max | $1.80 | $3.80 |
| `supercosmos-heavy` | SuperCosmos | Heavy | $2.00 | $4.40 |
**Long-context input above 262K tokens: 1.5×** (SuperCosmos): a request whose prompt is over 262K tokens bills its whole input at 1.5× the rate above.
The family id `supercosmos` with `effort` (or `reasoning_effort` `low` / `medium` / `high`) works too. Line Code ids answer `410 model_retired` ([details](/models/line-code-retired)).
## Errors
Errors use the OpenAI shape: `{"error": {"message", "type", "code", "param"}}`. Every response has an `X-Request-Id`.
| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request`, `invalid_json`, `unsupported_content`, `unsupported_parameter`, `invalid_effort` | The request isn't valid |
| 401 | `invalid_api_key`, `expired_api_key`, `missing_account_id`, `account_mismatch` | Key or Account ID problem |
| 402 | `out_of_credits` | Trial and credit balance used up |
| 403 | `insufficient_scope` | The key lacks `models:invoke` |
| 404 | `model_not_found`, `not_supported` | Unknown model or endpoint |
| 413 | `request_too_large` | Over 3 MB or 800 messages |
| 429 | `rate_limited` | The key's per-minute limit; see `Retry-After` |
| 502 / 503 / 504 | `model_overloaded`, `model_unavailable`, `model_timeout`, `empty_response`, `stream_error` | Retry with backoff; `Retry-After` when sent |
A stream that fails midway sends `data: {"error": {...}}` and then `data: [DONE]`.
## Rate limits
Each key has its own limit (10, 30, 60 or 120 requests per minute). Responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`.
---
Source: https://developers.clatterlabs.com/api-reference/model-api/models/list
# List models
> The model ids you can call, with their prices.
`GET https://api.gateway.clatterlabs.xyz/v1/models`
Returns every SuperCosmos 1.1 model id with its effort, capabilities and price per 1M tokens, plus retired ids. No key needed.
## Response
- `object` (string): Always `list`.
- `data` (Model[]): One entry per model id: `id`, `name`, `family`, `version`, `effort`, `capabilities`, `max_output_tokens` and `pricing` (`input` and `output` in USD per 1M tokens). The list shows only the first entry; the response has `supercosmos-flash`, `supercosmos-max` and `supercosmos-heavy`.
- `families` (object[]): The family id `supercosmos` with its version, context window, size, efforts and default effort.
- `retired` (object[]): Retired models: their ids, retirement date and replacement. Calling them answers `410 model_retired`.
## Example request
```bash
curl "https://api.gateway.clatterlabs.xyz/v1/models" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Example response
```json
{
"object": "list",
"data": [
{
"id": "supercosmos-flash",
"object": "model",
"created": 1793232000,
"owned_by": "clatter-labs",
"name": "SuperCosmos Flash",
"family": "SuperCosmos",
"version": "1.1",
"effort": "flash",
"description": "Fastest SuperCosmos effort. Quick answers, tool loops and everyday tasks.",
"capabilities": {
"chat_completions": true,
"streaming": true,
"tools": true,
"reasoning": false,
"vision": false
},
"max_output_tokens": 32768,
"pricing": {
"currency": "USD",
"unit": "1M tokens",
"input": 1.6,
"output": 3.4,
"long_context": "Long-context input above 262K tokens: 1.5x"
}
}
],
"families": [
{
"id": "supercosmos",
"name": "SuperCosmos",
"version": "1.1",
"context_window": 1048576,
"context_label": "1M",
"parameters": {
"total": "550B",
"active": "55B",
"architecture": "Mixture-of-Experts"
},
"efforts": [
"flash",
"max",
"heavy"
],
"default_effort": "flash"
}
],
"retired": [
{
"id": "line-code",
"ids": [
"line-code-fast",
"line-code-ultra",
"line-code-ultra-fast"
],
"retired_at": "2026-11-01",
"replacement": "supercosmos",
"status": 410,
"code": "model_retired"
}
]
}
```
---
Source: https://developers.clatterlabs.com/api-reference/model-api/models/get
# Retrieve a model
> One model id with its price.
`GET https://api.gateway.clatterlabs.xyz/v1/models/{model}`
Returns one model. No key needed.
## Path parameters
- `model` (string, required): A model id, like `supercosmos-max`.
## Response
- `id` (string): The model id.
- `pricing` (object): `input` and `output` in USD per 1M tokens.
## Example request
```bash
curl "https://api.gateway.clatterlabs.xyz/v1/models/MODEL" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `404` | `model_not_found` | Unknown model id. |
| `410` | `model_retired` | A retired model id (Line Code). See [Line Code retirement](/models/line-code-retired). |
## Example response
```json
{
"id": "supercosmos-max",
"object": "model",
"created": 1793232000,
"owned_by": "clatter-labs",
"name": "SuperCosmos Max",
"family": "SuperCosmos",
"version": "1.1",
"effort": "max",
"description": "Plans and builds. Multi-step work, debugging and longer answers.",
"capabilities": {
"chat_completions": true,
"streaming": true,
"tools": true,
"reasoning": true,
"vision": false
},
"max_output_tokens": 32768,
"pricing": {
"currency": "USD",
"unit": "1M tokens",
"input": 1.8,
"output": 3.8,
"long_context": "Long-context input above 262K tokens: 1.5x"
}
}
```
---
Source: https://developers.clatterlabs.com/api-reference/model-api/chat-completions
# Create a chat completion
> Send messages to a SuperCosmos 1.1 model and get a reply, streamed or not, with tool calls and token usage.
`POST https://api.gateway.clatterlabs.xyz/v1/chat/completions` (key permission: `models:invoke`)
Creates a model reply for the conversation. Billed per token at the price of the model id, from your credits (plans don't cover API calls).
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create it in [Console › API keys](https://console.clatterlabs.com/api-keys) with the **models:invoke** permission (preset **Model API**).
- `X-Clatter-Account` (string, required): The Account ID that owns the key, like `CL-7K2M9QXA` (Console › Settings). A missing value answers `401 missing_account_id`; someone else's answers `401 account_mismatch`.
## Body
- `model` (string, required): A model id: `supercosmos-flash`, `supercosmos-max` or `supercosmos-heavy`. Or the family id `supercosmos` with `effort`.
- `messages` (object[], required): The conversation: `system`, `developer`, `user`, `assistant` (with optional `tool_calls`) and `tool` (with `tool_call_id`) messages. Content is a string or an array of `{"type": "text"}` parts. Up to 800 messages.
- `stream` (boolean, default false): `true` streams server-sent events (`chat.completion.chunk`) ending with `data: [DONE]`.
- `stream_options` (object): `{"include_usage": true}` adds a final chunk with `usage` and empty `choices`.
- `tools` (object[]): Up to 64 function tools: `{"type": "function", "function": {"name", "description", "parameters"}}`.
- `tool_choice` (string | object): `auto` (default), `none`, `required`, or a specific function.
- `effort` (string): With the family id: `flash` / `max` / `heavy`. `reasoning_effort` `low` / `medium` / `high` works too.
- `max_tokens` (integer): Most output tokens (reasoning included). `max_completion_tokens` is accepted too. Capped per model (24,576 to 49,152).
- `temperature` (number): 0 to 2.
- `top_p` (number): Nucleus sampling, (0, 1].
- `stop` (string | string[]): Up to 4 stop sequences.
- `seed` (integer): Best-effort repeatable sampling.
- `presence_penalty` (number): Passed to the model.
- `frequency_penalty` (number): Passed to the model.
## Response
- `id` (string): `chatcmpl-…`. The same id is the request's entry in Console › Logs.
- `model` (string): The model id that answered.
- `choices[0].message` (object): `role`, `content`, `tool_calls` (when the model calls tools) and `reasoning_content` (Max and Heavy).
- `choices[0].finish_reason` (string): `stop`, `length` or `tool_calls`.
- `usage` (object): `prompt_tokens`, `completion_tokens` (reasoning included) and `total_tokens`: what's billed.
## Example request
```bash
curl https://api.gateway.clatterlabs.xyz/v1/chat/completions \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"model": "supercosmos-flash",
"messages": [{"role": "user", "content": "Write a haiku about the sea."}]
}'
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `400` | `invalid_request / unsupported_content / unsupported_parameter / invalid_effort` | The body isn't valid, has image parts, asks for `n` > 1 or `logprobs`, or names an unknown effort. |
| `401` | `invalid_api_key / expired_api_key / missing_account_id / account_mismatch` | The key or Account ID is wrong. |
| `402` | `out_of_credits` | Your credits are used up. Add credits in Console › Billing › Credits. |
| `403` | `insufficient_scope` | The key doesn't have `models:invoke`. |
| `403` | `account_suspended` | Your account is paused for 24 hours under the [Abuse policy](/policies/abuse). The body has `resets_at`; wait for `Retry-After`. |
| `404` | `model_not_found` | Unknown model id. |
| `410` | `model_retired` | A retired model id (Line Code). Use a SuperCosmos id. See [Line Code retirement](/models/line-code-retired). |
| `429` | `rate_limited` | The key's requests-per-minute limit is reached. Wait for `Retry-After`. |
| `503` | `model_overloaded / model_unavailable` | The model is at capacity or briefly unavailable. Retry after `Retry-After`. |
## Example response
```json
{
"id": "chatcmpl-c12f22770a744952a4457d3a",
"object": "chat.completion",
"created": 1793280843,
"model": "supercosmos-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Waves fold into foam,\nsalt wind carries gull voices,\nthe tide keeps its time."
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 148,
"completion_tokens": 22,
"total_tokens": 170
}
}
```
Any OpenAI SDK works: set the base URL to `https://api.gateway.clatterlabs.xyz/v1` and add `X-Clatter-Account` as a default header. See the [quickstart](/model-api/quickstart).
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/introduction
# 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.
First upload in five minutes.Codes and what to do.
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/authentication
# Authentication
> API keys plus your Account ID on every request.
Code Buckets uses the same **API keys** as the rest of the Clatter Labs Console. Create them in [Console › API keys](https://console.clatterlabs.com/api-keys). Each request carries two headers:
`Bearer clsk_...`: your API key.
The Account ID that owns the key, like `CL-7K2M9QXA` (Console › Settings). Matching is case-insensitive.
```bash
curl https://api.codebuckets.clatterlabs.xyz/v1/projects \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Permissions
Give a key only what it needs:
| Permission | Allows |
| --- | --- |
| `buckets:read` | List and read projects, buckets, objects, the code tree, files, events, backups; download; usage |
| `buckets:write` | Create, update and delete projects and buckets; upload; delete objects |
| `backups:write` | Create, restore and delete backups |
| `account:read` | Read usage (`GET /v1/usage`) |
A key with none of the Code Buckets permissions answers `403 insufficient_scope`.
| Situation | Response |
| --- | --- |
| No `X-Clatter-Account` | `401 missing_account_id` |
| Account ID doesn't own the key | `401 account_mismatch` |
| Key wrong or revoked | `401 invalid_api_key` |
| Key expired | `401 expired_api_key` |
| Key lacks the permission | `403 insufficient_scope` |
## Rate limits
Each key has a per-minute limit you choose in the Console (10, 30, 60 or 120). Chunk uploads and chunk downloads don't count toward it, so big transfers aren't throttled by it. Over the limit answers `429 rate_limited` with `Retry-After`.
Revoking a key in the Console stops it within 30 seconds.
## CORS
The API allows cross-origin requests. Keep keys on your server anyway: never put a `clsk_` key in front-end code.
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/errors
# Errors
> Error format, status codes and error codes.
Every error is JSON with a `code` to branch on and a `message` for people. Some errors add fields (like `missing_chunks`).
```json
{ "error": { "code": "bucket_full", "message": "This upload would take the bucket past its 10 GB limit (9.81 GB used, 0.00 GB in unfinished uploads).", "used_bytes": 10533397708, "pending_bytes": 0, "limit_bytes": 10737418240 } }
```
| Status | Code | What to do |
| --- | --- | --- |
| `400` | `bad_request` | A field is missing or invalid; the message says which |
| `400` | `bad_chunk`, `bad_chunk_size` | Use an index from 0 to `chunk_count - 1` and exactly `chunk_size` bytes (the last chunk is the remainder) |
| `400` | `checksum_mismatch` | The chunk changed on the way; send it again |
| `400` | `bad_ref`, `bad_path` | `ref` must be 40 hex characters; `path` a file path in the tree |
| `401` | `invalid_api_key`, `expired_api_key`, `missing_account_id`, `account_mismatch` | Check the key and the `X-Clatter-Account` header |
| `402` | `quota_exceeded` | This month's free tokens are used. [Contact us](https://help.clatterlabs.com/code-buckets/troubleshooting/cb-contact-support) for more |
| `403` | `insufficient_scope` | Create a key with the needed permission |
| `404` | `not_found` | The id doesn't exist on your account (or was deleted) |
| `409` | `limit_reached` | 100 projects per account, or 100 buckets per project |
| `409` | `project_not_empty` | Delete the project's buckets first |
| `409` | `upload_incomplete` | Send the chunks in `missing_chunks`, then complete again |
| `409` | `upload_closed` | The upload is already complete (or aborted) |
| `409` | `not_ready` | Wait for the upload to complete |
| `409` | `backup_limit` | Free keeps 1 backup: pass `"replace": true` or delete it |
| `413` | `bucket_full` | The bucket would pass 10 GB; delete objects or use another bucket |
| `413` | `too_large` | The file or body is over the limit |
| `413` | `use_chunks` | Over 1 GB: download chunk by chunk |
| `429` | `rate_limited` | Wait `Retry-After` seconds |
| `502` | `storage_error` | Retry; chunk operations are safe to repeat |
| `503` | `unavailable`, `storage_unavailable` | Retry in a moment |
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/projects/list
# List projects
> Your projects, newest first.
`GET https://api.codebuckets.clatterlabs.xyz/v1/projects` (key permission: `buckets:read`)
Returns your Code Buckets projects, newest first, each with its bucket count.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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`.
## Query parameters
- `limit` (integer, default 50): How many to return, 1 to 100.
- `before` (string): A `created_at` (or `at`) timestamp: return items before it, for paging.
## Response
- `object` (string): Always `list`.
- `data` (Project[]): Projects, newest first.
- `has_more` (boolean): `true` when older projects exist: pass the last `created_at` as `before`.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/projects?limit=20" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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. |
## Example response
```json
{
"object": "list",
"data": [
{
"object": "project",
"id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "storefront",
"description": "Web shop and its assets",
"buckets": 1,
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
],
"has_more": false
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/projects/create
# Create a project
> Make a project and get its Project ID.
`POST https://api.codebuckets.clatterlabs.xyz/v1/projects` (key permission: `buckets:write`)
Creates a project. The response carries its **Project ID** (`cbp_…`), which you use in every bucket call. An account can have up to 100 projects.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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`.
## Body
- `name` (string, required): Up to 80 characters.
- `description` (string): Up to 500 characters.
## Response
- `object` (string): Always `project`.
- `id` (string): The Project ID, like `cbp_4k9x2m7q1n8v3c6z0b5w`. Stable for the life of the project.
- `project_id` (string): Same as `id`, for convenience.
- `name` (string): The project's name.
- `description` (string | null): Your description.
- `buckets` (integer): How many buckets the project has.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/projects" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "storefront",
"description": "Web shop and its assets"
}'
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | `name` is missing or too long. |
| `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. |
| `409` | `limit_reached` | You already have 100 projects. |
## Example response
```json
{
"object": "project",
"id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "storefront",
"description": "Web shop and its assets",
"buckets": 0,
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/projects/get
# Get a project
> One project by its Project ID.
`GET https://api.codebuckets.clatterlabs.xyz/v1/projects/{project_id}` (key permission: `buckets:read`)
Returns the project with its bucket count.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `project_id` (string, required): The Project ID (`cbp_…`).
## Response
- `object` (string): Always `project`.
- `id` (string): The Project ID, like `cbp_4k9x2m7q1n8v3c6z0b5w`. Stable for the life of the project.
- `project_id` (string): Same as `id`, for convenience.
- `name` (string): The project's name.
- `description` (string | null): Your description.
- `buckets` (integer): How many buckets the project has.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 project with that id on your account. |
## Example response
```json
{
"object": "project",
"id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "storefront",
"description": "Web shop and its assets",
"buckets": 1,
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/projects/update
# Update a project
> Rename a project or change its description.
`PATCH https://api.codebuckets.clatterlabs.xyz/v1/projects/{project_id}` (key permission: `buckets:write`)
Changes only the fields you send. The Project ID never changes. Recorded as a `project.updated` event.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `project_id` (string, required): The Project ID (`cbp_…`).
## Body
- `name` (string): Up to 80 characters.
- `description` (string | null): Up to 500 characters; send `null` to clear it.
## Response
- `object` (string): Always `project`.
- `id` (string): The Project ID, like `cbp_4k9x2m7q1n8v3c6z0b5w`. Stable for the life of the project.
- `project_id` (string): Same as `id`, for convenience.
- `name` (string): The project's name.
- `description` (string | null): Your description.
- `buckets` (integer): How many buckets the project has.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl -X PATCH "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "storefront-v2"
}'
```
## 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 project with that id on your account. |
## Example response
```json
{
"object": "project",
"id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "storefront-v2",
"description": "Web shop and its assets",
"buckets": 1,
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/projects/delete
# Delete a project
> Remove an empty project.
`DELETE https://api.codebuckets.clatterlabs.xyz/v1/projects/{project_id}` (key permission: `buckets:write`)
Deletes a project that has no buckets left. It disappears from your lists and the API.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `project_id` (string, required): The Project ID (`cbp_…`).
## Response
- `object` (string): `project`.
- `id` (string): The Project ID.
- `deleted` (boolean): `true`.
## Example request
```bash
curl -X DELETE "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 project with that id on your account. |
| `409` | `project_not_empty` | Delete the project's buckets first. |
## Example response
```json
{
"object": "project",
"id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"deleted": true
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/projects/events
# List project events
> Everything that happened in a project.
`GET https://api.codebuckets.clatterlabs.xyz/v1/projects/{project_id}/events` (key permission: `buckets:read`)
The project's events feed, newest first: project changes plus every event in its buckets.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `project_id` (string, required): The Project ID (`cbp_…`).
## Query parameters
- `limit` (integer, default 50): How many to return, 1 to 100.
- `before` (string): A `created_at` (or `at`) timestamp: return items before it, for paging.
- `type` (string): Only this event type (`backup.restored`), or a prefix ending in a dot (`upload.`).
## Response
- `object` (string): `list`.
- `data` (Event[]): Events, newest first.
- `has_more` (boolean): More events exist.
- `next_before` (string | null): Pass as `before` for the next page.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID/events?limit=20" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 project with that id on your account. |
## Example response
```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
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/buckets/list
# List buckets
> The buckets in a project.
`GET https://api.codebuckets.clatterlabs.xyz/v1/projects/{project_id}/buckets` (key permission: `buckets:read`)
Returns the project's buckets, newest first, with storage use.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `project_id` (string, required): The Project ID (`cbp_…`).
## Response
- `object` (string): `list`.
- `data` (Bucket[]): Buckets. See [Get a bucket](/api-reference/code-buckets/buckets/get) for the fields.
- `has_more` (boolean): Always `false` (up to 100 buckets per project).
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID/buckets" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 project with that id on your account. |
## Example response
```json
{
"object": "list",
"data": [
{
"object": "bucket",
"id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "web",
"description": null,
"preview": true,
"visibility": "private",
"code": {
"ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"files": 1284,
"bytes": 18734211
},
"storage": {
"used_bytes": 131204115,
"pending_bytes": 0,
"limit_bytes": 10737418240
},
"encryption": {
"algorithm": "AES-256-GCM",
"key": "per-bucket data key, wrapped by a Clatter Labs master key"
},
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
],
"has_more": false
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/buckets/create
# Create a bucket
> Add a bucket to a project.
`POST https://api.codebuckets.clatterlabs.xyz/v1/projects/{project_id}/buckets` (key permission: `buckets:write`)
Creates an empty bucket with its own encryption key. A project can have up to 100 buckets; each holds up to 10 GB.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `project_id` (string, required): The Project ID (`cbp_…`).
## Body
- `name` (string, required): Up to 80 characters.
- `description` (string): Up to 500 characters.
- `preview` (boolean, default true): Unpack uploaded zips into a browsable code tree. `false` keeps code only in encrypted archives.
## Response
- `object` (string): Always `bucket`.
- `id` (string): The bucket id, like `cbk_q7c1r9t2y6u0i3o8p5a4`.
- `project_id` (string): The Project ID it belongs to.
- `name / description` (string): Your name and description.
- `preview` (boolean): Whether uploaded zips are unpacked into a browsable code tree.
- `visibility` (string): `private` (default) or `public`. In a public bucket, every stored file that follows the bucket default has a public link. See [Public files](/code-buckets/public-files).
- `code` (object): `{ ref, files, bytes }`: the current code tree. `ref` is `null` until the first zip is unpacked.
- `storage` (object): `{ used_bytes, pending_bytes, limit_bytes }`. `used_bytes` counts stored zips and assets; `pending_bytes` is reserved by unfinished uploads; the limit is 10 GB (10,737,418,240 bytes).
- `encryption` (object): How stored files are encrypted.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID/buckets" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "web",
"preview": true
}'
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | `name` is missing or too long. |
| `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 project with that id on your account. |
| `409` | `limit_reached` | The project already has 100 buckets. |
| `503` | `storage_unavailable` | Storage couldn't be set up; try again. |
## Example response
```json
{
"object": "bucket",
"id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "web",
"description": null,
"preview": true,
"visibility": "private",
"code": {
"ref": null,
"files": 0,
"bytes": 0
},
"storage": {
"used_bytes": 0,
"pending_bytes": 0,
"limit_bytes": 10737418240
},
"encryption": {
"algorithm": "AES-256-GCM",
"key": "per-bucket data key, wrapped by a Clatter Labs master key"
},
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/buckets/get
# Get a bucket
> A bucket with its code tree and storage use.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}` (key permission: `buckets:read`)
Returns the bucket, its current code `ref`, and how much of its 10 GB is used.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Response
- `object` (string): Always `bucket`.
- `id` (string): The bucket id, like `cbk_q7c1r9t2y6u0i3o8p5a4`.
- `project_id` (string): The Project ID it belongs to.
- `name / description` (string): Your name and description.
- `preview` (boolean): Whether uploaded zips are unpacked into a browsable code tree.
- `visibility` (string): `private` (default) or `public`. In a public bucket, every stored file that follows the bucket default has a public link. See [Public files](/code-buckets/public-files).
- `code` (object): `{ ref, files, bytes }`: the current code tree. `ref` is `null` until the first zip is unpacked.
- `storage` (object): `{ used_bytes, pending_bytes, limit_bytes }`. `used_bytes` counts stored zips and assets; `pending_bytes` is reserved by unfinished uploads; the limit is 10 GB (10,737,418,240 bytes).
- `encryption` (object): How stored files are encrypted.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 bucket with that id on your account. |
## Example response
```json
{
"object": "bucket",
"id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "web",
"description": null,
"preview": true,
"visibility": "private",
"code": {
"ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"files": 1284,
"bytes": 18734211
},
"storage": {
"used_bytes": 131204115,
"pending_bytes": 0,
"limit_bytes": 10737418240
},
"encryption": {
"algorithm": "AES-256-GCM",
"key": "per-bucket data key, wrapped by a Clatter Labs master key"
},
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/buckets/update
# Update a bucket
> Rename a bucket or turn preview on or off.
`PATCH https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}` (key permission: `buckets:write`)
Changes only the fields you send. Turning `preview` off stops new zips from being unpacked; the existing tree stays until the next upload.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Body
- `name` (string): Up to 80 characters.
- `description` (string | null): Up to 500 characters.
- `preview` (boolean): Unpack new zips into the code tree.
- `visibility` (string): `private` or `public`. Same as [Set bucket visibility](/api-reference/code-buckets/visibility/bucket).
## Response
- `object` (string): Always `bucket`.
- `id` (string): The bucket id, like `cbk_q7c1r9t2y6u0i3o8p5a4`.
- `project_id` (string): The Project ID it belongs to.
- `name / description` (string): Your name and description.
- `preview` (boolean): Whether uploaded zips are unpacked into a browsable code tree.
- `visibility` (string): `private` (default) or `public`. In a public bucket, every stored file that follows the bucket default has a public link. See [Public files](/code-buckets/public-files).
- `code` (object): `{ ref, files, bytes }`: the current code tree. `ref` is `null` until the first zip is unpacked.
- `storage` (object): `{ used_bytes, pending_bytes, limit_bytes }`. `used_bytes` counts stored zips and assets; `pending_bytes` is reserved by unfinished uploads; the limit is 10 GB (10,737,418,240 bytes).
- `encryption` (object): How stored files are encrypted.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl -X PATCH "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"preview": false
}'
```
## 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 bucket with that id on your account. |
## Example response
```json
{
"object": "bucket",
"id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "web",
"description": null,
"preview": false,
"visibility": "private",
"code": {
"ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"files": 1284,
"bytes": 18734211
},
"storage": {
"used_bytes": 131204115,
"pending_bytes": 0,
"limit_bytes": 10737418240
},
"encryption": {
"algorithm": "AES-256-GCM",
"key": "per-bucket data key, wrapped by a Clatter Labs master key"
},
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/buckets/delete
# Delete a bucket
> Remove a bucket from its project.
`DELETE https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}` (key permission: `buckets:write`)
Deletes the bucket. It disappears from the project and the API and stops counting toward your usage.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Response
- `object` (string): `bucket`.
- `id` (string): The bucket id.
- `deleted` (boolean): `true`.
## Example request
```bash
curl -X DELETE "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 bucket with that id on your account. |
## Example response
```json
{
"object": "bucket",
"id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"deleted": true
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/buckets/events
# List bucket events
> The bucket's change feed.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/events` (key permission: `buckets:read`)
Every upload, code change, deletion, backup, restore and key action in the bucket, newest first.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Query parameters
- `limit` (integer, default 50): How many to return, 1 to 100.
- `before` (string): A `created_at` (or `at`) timestamp: return items before it, for paging.
- `type` (string): Only this event type, or a prefix ending in a dot (`backup.`).
## Response
- `object` (string): Always `event`.
- `id` (string): The event id (`cbe_…`).
- `type` (string): What happened, like `upload.completed` or `backup.restored`. See [Events](/code-buckets/events) for the full list.
- `summary` (string): One line for people.
- `project_id / bucket_id` (string): Where it happened (`bucket_id` is `null` for project events).
- `actor` (object): Who did it: `{ type: "api_key", key_id, key_name }`, `{ type: "console" }` or `{ type: "system" }`.
- `data` (object): Details for the type (ids, sizes, refs).
- `at` (string): ISO 8601 timestamp.
## Example request
```bash
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"
```
## 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 bucket with that id on your account. |
## Example response
```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
}
```
The response is a list (`object`, `data`, `has_more`, `next_before`); the fields above describe each event in `data`.
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/uploads/create
# Start an upload
> Open a resumable upload for a zip or an asset.
`POST https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/uploads` (key permission: `buckets: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](/api-reference/code-buckets/uploads/chunk), then [complete the upload](/api-reference/code-buckets/uploads/complete).
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Body
- `name` (string, required): The file name, like `storefront.zip` (no slashes, up to 255 characters).
- `size` (integer, required): The exact file size in bytes.
- `kind` (string): `archive` or `asset`. Defaults to `archive` for `.zip` names, `asset` otherwise.
- `target_path` (string): Archives only: unpack into this folder (like `packages/api`) and keep the rest of the tree. Omit to replace the whole tree.
- `content_type` (string): MIME type returned on download.
- `visibility` (string): `inherit` (default: follow the bucket), `private` or `public`. Pass `public` to get a public link as soon as the upload completes.
## Response
- `object` (string): `upload` while it's being uploaded, then `object`.
- `id` (string): The upload id, which is also the stored object's id (`cbo_…`).
- `bucket_id` (string): The bucket it belongs to.
- `kind` (string): `archive` (a zip of code) or `asset` (any other file).
- `name` (string): The file name.
- `target_path` (string): Archives only: the folder the zip is unpacked into (`""` = the whole tree).
- `size` (integer): Size in bytes.
- `chunk_size` (integer): Bytes per chunk: 16,777,216 (16 MiB).
- `chunk_count` (integer): How many chunks the file has.
- `status` (string): `uploading`, `processing` (building the preview), `ready` or `failed`.
- `received_chunks` (integer[]): While `uploading`: the chunk indexes already stored. Upload only the missing ones to resume.
- `preview` (object): 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.
- `visibility` (string): The file's own setting: `inherit` (default: follow the bucket), `private` or `public`.
- `effective_visibility` (string): What applies now: `private` or `public` (the file's setting, or the bucket's when it's `inherit`).
- `public_url` (string | null): The file's public link while it's public and stored, `null` otherwise. Images (`image/*`) get `https://img.cdn.clatterlabs.xyz/`; everything else `https://files.cdn-buckets.clatterlabs.xyz//`. See [Public files](/code-buckets/public-files).
- `served_as` (string): `image` (public link on img.cdn.clatterlabs.xyz, cached for a year) or `file` (files.cdn-buckets.clatterlabs.xyz).
- `encrypted` (boolean): Always `true`.
- `created_at / completed_at` (string): ISO 8601 timestamps.
## Example request
```bash
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
}'
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | A field is missing or invalid. |
| `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 bucket with that id on your account. |
| `413` | `bucket_full` | The upload would take the bucket past 10 GB (counting unfinished uploads). |
| `503` | `storage_unavailable` | Try again. |
## Example response
```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
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/uploads/chunk
# Upload a chunk
> Send one 16 MiB part of the file.
`PUT https://api.codebuckets.clatterlabs.xyz/v1/uploads/{upload_id}/chunks/{index}` (key permission: `buckets:write`)
Stores one chunk, encrypted. Chunk `index` covers bytes `index × chunk_size` up to the next chunk; every chunk is exactly `chunk_size` bytes except the last. Send chunks in any order and in parallel (up to 4 at a time works well). Sending a chunk again replaces it, so retries are safe. Chunk requests don't count toward the key's per-minute limit.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `upload_id` (string, required): The upload id (`cbo_…`) from [Start an upload](/api-reference/code-buckets/uploads/create).
- `index` (integer, required): 0 to `chunk_count - 1`.
## Response
- `object` (string): `upload.chunk`.
- `upload_id` (string): The upload.
- `index` (integer): The chunk index.
- `size` (integer): Bytes stored.
- `sha256` (string): SHA-256 of the chunk (hex).
- `duplicate` (boolean): `true` when the same chunk was already stored.
## Example request
```bash
curl -X PUT "https://api.codebuckets.clatterlabs.xyz/v1/uploads/cbo_m2n8b4v6c1x9z3l7k5j0/chunks/0" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/octet-stream" \
--data-binary @part-00000
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_chunk / bad_chunk_size / checksum_mismatch` | Wrong index, wrong length, or the checksum didn't match. |
| `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 upload with that id on your account. |
| `409` | `upload_closed` | The upload is already complete. |
| `502` | `storage_error` | Retry the chunk. |
## Example response
```json
{
"object": "upload.chunk",
"upload_id": "cbo_m2n8b4v6c1x9z3l7k5j0",
"index": 0,
"size": 16777216,
"sha256": "4d9b0f3c…"
}
```
**Request body:** The raw chunk bytes (`Content-Type: application/octet-stream`). Optional header `X-Content-SHA256`: the chunk's SHA-256 in hex; a mismatch answers `400 checksum_mismatch`.
Split a file with `split -b 16777216 -d -a 5 storefront.zip part-` and send `part-00000`, `part-00001`, … as chunks 0, 1, …. The [Uploads guide](/code-buckets/uploads) has a full script in each language.
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/uploads/get
# Get an upload
> Check what's arrived, to resume.
`GET https://api.codebuckets.clatterlabs.xyz/v1/uploads/{upload_id}` (key permission: `buckets:read`)
Returns the upload. While it's `uploading`, `received_chunks` lists the chunks already stored: send only the missing ones, then complete.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `upload_id` (string, required): The upload id (`cbo_…`) from [Start an upload](/api-reference/code-buckets/uploads/create).
## Response
- `object` (string): `upload` while it's being uploaded, then `object`.
- `id` (string): The upload id, which is also the stored object's id (`cbo_…`).
- `bucket_id` (string): The bucket it belongs to.
- `kind` (string): `archive` (a zip of code) or `asset` (any other file).
- `name` (string): The file name.
- `target_path` (string): Archives only: the folder the zip is unpacked into (`""` = the whole tree).
- `size` (integer): Size in bytes.
- `chunk_size` (integer): Bytes per chunk: 16,777,216 (16 MiB).
- `chunk_count` (integer): How many chunks the file has.
- `status` (string): `uploading`, `processing` (building the preview), `ready` or `failed`.
- `received_chunks` (integer[]): While `uploading`: the chunk indexes already stored. Upload only the missing ones to resume.
- `preview` (object): 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.
- `visibility` (string): The file's own setting: `inherit` (default: follow the bucket), `private` or `public`.
- `effective_visibility` (string): What applies now: `private` or `public` (the file's setting, or the bucket's when it's `inherit`).
- `public_url` (string | null): The file's public link while it's public and stored, `null` otherwise. Images (`image/*`) get `https://img.cdn.clatterlabs.xyz/`; everything else `https://files.cdn-buckets.clatterlabs.xyz//`. See [Public files](/code-buckets/public-files).
- `served_as` (string): `image` (public link on img.cdn.clatterlabs.xyz, cached for a year) or `file` (files.cdn-buckets.clatterlabs.xyz).
- `encrypted` (boolean): Always `true`.
- `created_at / completed_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/uploads/UPLOAD_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 upload with that id on your account. |
## Example response
```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": [
0,
1,
2
],
"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
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/uploads/complete
# Complete an upload
> Finish the upload once every chunk is in.
`POST https://api.codebuckets.clatterlabs.xyz/v1/uploads/{upload_id}/complete` (key permission: `buckets:write`)
Checks that every chunk arrived and stores the file. An asset is `ready` right away. A zip in a bucket with preview on goes to `processing` while its code tree is built (usually seconds), then `ready`; a `code.updated` event records the new tree. Completing twice is safe.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `upload_id` (string, required): The upload id (`cbo_…`) from [Start an upload](/api-reference/code-buckets/uploads/create).
## Response
- `object` (string): `upload` while it's being uploaded, then `object`.
- `id` (string): The upload id, which is also the stored object's id (`cbo_…`).
- `bucket_id` (string): The bucket it belongs to.
- `kind` (string): `archive` (a zip of code) or `asset` (any other file).
- `name` (string): The file name.
- `target_path` (string): Archives only: the folder the zip is unpacked into (`""` = the whole tree).
- `size` (integer): Size in bytes.
- `chunk_size` (integer): Bytes per chunk: 16,777,216 (16 MiB).
- `chunk_count` (integer): How many chunks the file has.
- `status` (string): `uploading`, `processing` (building the preview), `ready` or `failed`.
- `received_chunks` (integer[]): While `uploading`: the chunk indexes already stored. Upload only the missing ones to resume.
- `preview` (object): 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.
- `visibility` (string): The file's own setting: `inherit` (default: follow the bucket), `private` or `public`.
- `effective_visibility` (string): What applies now: `private` or `public` (the file's setting, or the bucket's when it's `inherit`).
- `public_url` (string | null): The file's public link while it's public and stored, `null` otherwise. Images (`image/*`) get `https://img.cdn.clatterlabs.xyz/`; everything else `https://files.cdn-buckets.clatterlabs.xyz//`. See [Public files](/code-buckets/public-files).
- `served_as` (string): `image` (public link on img.cdn.clatterlabs.xyz, cached for a year) or `file` (files.cdn-buckets.clatterlabs.xyz).
- `encrypted` (boolean): Always `true`.
- `created_at / completed_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/uploads/UPLOAD_ID/complete" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 upload with that id on your account. |
| `409` | `upload_incomplete` | Chunks are missing; `error.missing_chunks` lists up to 50 of them. |
## Example response
```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": "processing",
"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": "2026-10-28T14:06:40.019Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/uploads/abort
# Abort an upload
> Cancel an unfinished upload.
`POST https://api.codebuckets.clatterlabs.xyz/v1/uploads/{upload_id}/abort` (key permission: `buckets:write`)
Cancels an upload that isn't complete and frees the space it reserved.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `upload_id` (string, required): The upload id (`cbo_…`) from [Start an upload](/api-reference/code-buckets/uploads/create).
## Response
- `object` (string): `upload`.
- `id` (string): The upload id.
- `status` (string): `aborted`.
## Example request
```bash
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/uploads/UPLOAD_ID/abort" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 upload with that id on your account. |
| `409` | `upload_closed` | Only unfinished uploads can be aborted. |
## Example response
```json
{
"object": "upload",
"id": "cbo_m2n8b4v6c1x9z3l7k5j0",
"status": "aborted"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/objects/list
# List objects
> The zips and assets stored in a bucket.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects` (key permission: `buckets:read`)
Stored zips and assets, newest first, including unfinished uploads (status `uploading`).
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Query parameters
- `limit` (integer, default 50): How many to return, 1 to 100.
- `before` (string): A `created_at` (or `at`) timestamp: return items before it, for paging.
- `kind` (string): `archive` or `asset`.
## Response
- `object` (string): `list`.
- `data` (Object[]): Objects. See [Get an object](/api-reference/code-buckets/objects/get).
- `has_more` (boolean): More exist.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/objects?kind=archive" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 bucket with that id on your account. |
## Example response
```json
{
"object": "list",
"data": [
{
"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"
}
],
"has_more": false
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/objects/get
# Get an object
> One stored zip or asset.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}` (key permission: `buckets:read`)
Returns the object, including its preview result for zips.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
- `object_id` (string, required): The object id (`cbo_…`).
## Response
- `object` (string): `upload` while it's being uploaded, then `object`.
- `id` (string): The upload id, which is also the stored object's id (`cbo_…`).
- `bucket_id` (string): The bucket it belongs to.
- `kind` (string): `archive` (a zip of code) or `asset` (any other file).
- `name` (string): The file name.
- `target_path` (string): Archives only: the folder the zip is unpacked into (`""` = the whole tree).
- `size` (integer): Size in bytes.
- `chunk_size` (integer): Bytes per chunk: 16,777,216 (16 MiB).
- `chunk_count` (integer): How many chunks the file has.
- `status` (string): `uploading`, `processing` (building the preview), `ready` or `failed`.
- `received_chunks` (integer[]): While `uploading`: the chunk indexes already stored. Upload only the missing ones to resume.
- `preview` (object): 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.
- `visibility` (string): The file's own setting: `inherit` (default: follow the bucket), `private` or `public`.
- `effective_visibility` (string): What applies now: `private` or `public` (the file's setting, or the bucket's when it's `inherit`).
- `public_url` (string | null): The file's public link while it's public and stored, `null` otherwise. Images (`image/*`) get `https://img.cdn.clatterlabs.xyz/`; everything else `https://files.cdn-buckets.clatterlabs.xyz//`. See [Public files](/code-buckets/public-files).
- `served_as` (string): `image` (public link on img.cdn.clatterlabs.xyz, cached for a year) or `file` (files.cdn-buckets.clatterlabs.xyz).
- `encrypted` (boolean): Always `true`.
- `created_at / completed_at` (string): ISO 8601 timestamps.
## Example request
```bash
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"
```
## 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. |
## Example response
```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"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/objects/download
# Download an object
> The whole file, decrypted.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}/content` (key permission: `buckets:read`)
Streams the original file back, decrypted, with `Content-Disposition: attachment`. Objects over 1 GB download chunk by chunk with [Download a chunk](/api-reference/code-buckets/objects/chunk).
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
- `object_id` (string, required): The object id (`cbo_…`).
## Response
- `(body)` (binary): The file's bytes, `Content-Length` set.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/cbk_q7c1r9t2y6u0i3o8p5a4/objects/cbo_m2n8b4v6c1x9z3l7k5j0/content" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-o storefront.zip
```
## 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. |
| `413` | `use_chunks` | Over 1 GB: download chunks; `error.chunk_count` tells you how many. |
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/objects/chunk
# Download a chunk
> One 16 MiB part of a stored file.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}/chunks/{index}` (key permission: `buckets:read`)
Returns chunk `index` decrypted, with its SHA-256 in the `X-Content-SHA256` header. Concatenate chunks 0 to `chunk_count - 1` to rebuild the file. Doesn't count toward the key's per-minute limit.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
- `object_id` (string, required): The object id (`cbo_…`).
- `index` (integer, required): 0 to `chunk_count - 1`.
## Response
- `(body)` (binary): The chunk's bytes.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/cbk_q7c1r9t2y6u0i3o8p5a4/objects/cbo_m2n8b4v6c1x9z3l7k5j0/chunks/0" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-o part-00000
```
## 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. |
| `400` | `bad_chunk` | Index out of range. |
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/objects/delete
# Delete an object
> Remove a stored zip or asset.
`DELETE https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}` (key permission: `buckets:write`)
Deletes the object from the bucket; it stops counting toward the 10 GB. The code tree isn't changed. A backup taken while the object was stored brings it back on restore.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
- `object_id` (string, required): The object id (`cbo_…`).
## Response
- `object` (string): `object`.
- `id` (string): The object id.
- `deleted` (boolean): `true`.
## Example request
```bash
curl -X DELETE "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"
```
## 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. |
## Example response
```json
{
"object": "object",
"id": "cbo_m2n8b4v6c1x9z3l7k5j0",
"deleted": true
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/visibility/object
# Set file visibility
> Make one stored file public or private.
`PATCH https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}/visibility` (key permission: `buckets: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/`, 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
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
- `object_id` (string, required): The object id (`cbo_…`) of a stored zip or asset.
## Body
- `visibility` (string, required): `public`, `private` or `inherit`.
## Response
- `object` (string): `upload` while it's being uploaded, then `object`.
- `id` (string): The upload id, which is also the stored object's id (`cbo_…`).
- `bucket_id` (string): The bucket it belongs to.
- `kind` (string): `archive` (a zip of code) or `asset` (any other file).
- `name` (string): The file name.
- `target_path` (string): Archives only: the folder the zip is unpacked into (`""` = the whole tree).
- `size` (integer): Size in bytes.
- `chunk_size` (integer): Bytes per chunk: 16,777,216 (16 MiB).
- `chunk_count` (integer): How many chunks the file has.
- `status` (string): `uploading`, `processing` (building the preview), `ready` or `failed`.
- `received_chunks` (integer[]): While `uploading`: the chunk indexes already stored. Upload only the missing ones to resume.
- `preview` (object): 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.
- `visibility` (string): The file's own setting: `inherit` (default: follow the bucket), `private` or `public`.
- `effective_visibility` (string): What applies now: `private` or `public` (the file's setting, or the bucket's when it's `inherit`).
- `public_url` (string | null): The file's public link while it's public and stored, `null` otherwise. Images (`image/*`) get `https://img.cdn.clatterlabs.xyz/`; everything else `https://files.cdn-buckets.clatterlabs.xyz//`. See [Public files](/code-buckets/public-files).
- `served_as` (string): `image` (public link on img.cdn.clatterlabs.xyz, cached for a year) or `file` (files.cdn-buckets.clatterlabs.xyz).
- `encrypted` (boolean): Always `true`.
- `created_at / completed_at` (string): ISO 8601 timestamps.
## Example request
```bash
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"
}'
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | `visibility` isn't `public`, `private` or `inherit`. |
| `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 bucket or object with that id on your account. |
| `409` | `not_ready` | The upload isn't complete yet. |
## Example response
```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"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/visibility/bucket
# Set bucket visibility
> Make a whole bucket public or private.
`PATCH https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/visibility` (key permission: `buckets:write`)
Sets the bucket's default to `public` or `private` (new buckets are private). Every stored file whose own setting is `inherit` follows it; files set to `private` or `public` keep their own setting. The code preview tree is never public. Recorded as a `bucket.visibility_changed` event.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Body
- `visibility` (string, required): `public` or `private`.
## Response
- `object` (string): Always `bucket`.
- `id` (string): The bucket id, like `cbk_q7c1r9t2y6u0i3o8p5a4`.
- `project_id` (string): The Project ID it belongs to.
- `name / description` (string): Your name and description.
- `preview` (boolean): Whether uploaded zips are unpacked into a browsable code tree.
- `visibility` (string): `private` (default) or `public`. In a public bucket, every stored file that follows the bucket default has a public link. See [Public files](/code-buckets/public-files).
- `code` (object): `{ ref, files, bytes }`: the current code tree. `ref` is `null` until the first zip is unpacked.
- `storage` (object): `{ used_bytes, pending_bytes, limit_bytes }`. `used_bytes` counts stored zips and assets; `pending_bytes` is reserved by unfinished uploads; the limit is 10 GB (10,737,418,240 bytes).
- `encryption` (object): How stored files are encrypted.
- `created_at / updated_at` (string): ISO 8601 timestamps.
## Example request
```bash
curl -X PATCH "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/visibility" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"visibility": "public"
}'
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `400` | `bad_request` | `visibility` isn't `public` or `private`. |
| `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 bucket with that id on your account. |
## Example response
```json
{
"object": "bucket",
"id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "web",
"description": null,
"preview": true,
"visibility": "public",
"code": {
"ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"files": 1284,
"bytes": 18734211
},
"storage": {
"used_bytes": 131204115,
"pending_bytes": 0,
"limit_bytes": 10737418240
},
"encryption": {
"algorithm": "AES-256-GCM",
"key": "per-bucket data key, wrapped by a Clatter Labs master key"
},
"created_at": "2026-10-28T14:05:11.482Z",
"updated_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/visibility/public-url
# Get a public URL
> A stored file's stable public link, and whether it works right now.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/objects/{object_id}/public-url` (key permission: `buckets:read`)
Returns the file's public link: `https://img.cdn.clatterlabs.xyz/` for images (`image/*`), `https://files.cdn-buckets.clatterlabs.xyz//` for everything else. `public` says whether it works right now. An image's id is replaced when it stops being public, so ask again after making it public.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
- `object_id` (string, required): The object id (`cbo_…`) of a stored zip or asset.
## Response
- `object` (string): Always `public_url`.
- `object_id / bucket_id` (string): The file and its bucket.
- `url` (string): The public link (images: img.cdn.clatterlabs.xyz/; other files: files.cdn-buckets.clatterlabs.xyz//).
- `served_as` (string): `image` (public link on img.cdn.clatterlabs.xyz, cached for a year) or `file` (files.cdn-buckets.clatterlabs.xyz).
- `content_type` (string): The `Content-Type` the link is served with.
- `public` (boolean): `true` when the link works now.
- `visibility` (string): The file's own setting: `inherit`, `private` or `public`.
- `effective_visibility` (string): `public` or `private`: what applies now.
- `bucket_visibility` (string): The bucket's default.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/objects/OBJECT_ID/public-url" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 bucket or object with that id on your account. |
| `409` | `not_ready` | The upload isn't complete yet. |
## Example response
```json
{
"object": "public_url",
"object_id": "cbo_x4p8t2w6r1k9m3q7n5d0",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"url": "https://img.cdn.clatterlabs.xyz/V1StGXR8Z5jdHi6BmyT2kq",
"served_as": "image",
"content_type": "image/png",
"public": true,
"visibility": "inherit",
"effective_visibility": "public",
"bucket_visibility": "public"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/preview/tree
# Get the code tree
> Every file and folder in the bucket's code.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/tree` (key permission: `buckets:read`)
Lists the code tree as flat paths. Pass `ref` to read a specific version; responses for an explicit `ref` never change, so they're cached at the edge and come back fast.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Query parameters
- `ref` (string): A code ref (40 hex characters) from `bucket.code.ref`, an event, or a backup's `code_ref`. Defaults to the current tree.
## Response
- `object` (string): `tree`.
- `bucket_id` (string): The bucket.
- `ref` (string | null): The ref listed (`null` when there's no code yet).
- `files` (object[]): `{ path, type: "file", size }` and `{ path, type: "dir" }`, sorted by path.
- `truncated` (boolean): `true` for very large trees (over 100,000 entries).
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/tree?ref=9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 bucket with that id on your account. |
| `400` | `bad_ref` | `ref` isn't 40 hex characters. |
## Example response
```json
{
"object": "tree",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"files": [
{
"path": "README.md",
"type": "file",
"size": 1840
},
{
"path": "src",
"type": "dir"
},
{
"path": "src/index.ts",
"type": "file",
"size": 5121
}
],
"truncated": false
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/preview/file
# Get a file
> One file from the code tree, ready to display.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/files/{path}` (key permission: `buckets:read`)
Returns a file's content with a detected `language` for syntax highlighting. Text comes back as UTF-8; binary files as base64. Add `download=1` to get the raw bytes instead. Files up to 2 MB are in the code tree; bigger ones stay in their zip.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
- `path` (string, required): The file path, like `src/index.ts` (URL-encode each segment).
## Query parameters
- `ref` (string): A code ref; defaults to the current tree. With an explicit `ref` the response is cached.
- `download` (string): `1` returns the raw file bytes.
## Response
- `object` (string): `file`.
- `path` (string): The path.
- `ref` (string): The ref read.
- `size` (integer): Bytes.
- `binary` (boolean): `true` for binary files.
- `encoding` (string): `utf-8` or `base64`.
- `content` (string): The file content.
- `language` (string | null): Like `typescript`, `python`, `json`; `null` for unknown or binary.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/files/PATH?ref=9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 file at that path. |
| `400` | `bad_path / bad_ref` | Invalid path or ref. |
## Example response
```json
{
"object": "file",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"path": "src/index.ts",
"ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"size": 5121,
"binary": false,
"encoding": "utf-8",
"content": "import { serve } from \"./server\";\n…",
"language": "typescript"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/backups/list
# List backups
> The backups of a bucket.
`GET https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/backups` (key permission: `buckets:read`)
Returns the bucket's backups, newest first, and how many your plan includes.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Response
- `object` (string): `list`.
- `data` (Backup[]): Backups.
- `plan` (object): `{ backups_used, backups_included }` across your account (`backups_included` is `null` when unlimited).
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/backups" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 bucket with that id on your account. |
## Example response
```json
{
"object": "list",
"data": [
{
"object": "backup",
"id": "cbb_h3g7f1d9s5a2q8w4e6r0",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "Before checkout rewrite",
"code_ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"objects": 2,
"files": 1284,
"bytes": 131204115,
"created_at": "2026-10-28T14:05:11.482Z"
}
],
"has_more": false,
"plan": {
"backups_used": 1,
"backups_included": 1
}
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/backups/create
# Create a backup
> Snapshot a bucket's code and stored files.
`POST https://api.codebuckets.clatterlabs.xyz/v1/buckets/{bucket_id}/backups` (key permission: `backups:write`)
Captures the bucket's current code tree and the list of its stored zips and assets. The Free tier keeps 1 backup per account: send `"replace": true` to replace it.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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_id` (string, required): The bucket id (`cbk_…`).
## Body
- `name` (string): Up to 80 characters. Defaults to `Backup UTC`.
- `replace` (boolean, default false): On the Free tier, replace your existing backup instead of failing with `409 backup_limit`.
## Response
- `object` (string): Always `backup`.
- `id` (string): The backup id (`cbb_…`).
- `bucket_id / project_id` (string): Where it was taken.
- `name` (string): Its name.
- `code_ref` (string | null): The code tree it captured (`null` if the bucket had no code yet).
- `objects` (integer): How many stored zips and assets it covers.
- `files` (integer): Files in the captured code tree.
- `bytes` (integer): Total size of the stored files it covers.
- `created_at` (string): ISO 8601 timestamp.
## Example request
```bash
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/backups" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "Before checkout rewrite",
"replace": true
}'
```
## 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 bucket with that id on your account. |
| `409` | `backup_limit` | Your plan's backups are used; `error.existing_backup_id` names the one to replace. |
## Example response
```json
{
"object": "backup",
"id": "cbb_h3g7f1d9s5a2q8w4e6r0",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "Before checkout rewrite",
"code_ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"objects": 2,
"files": 1284,
"bytes": 131204115,
"created_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/backups/get
# Get a backup
> One backup.
`GET https://api.codebuckets.clatterlabs.xyz/v1/backups/{backup_id}` (key permission: `buckets:read`)
Returns the backup.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `backup_id` (string, required): The backup id (`cbb_…`).
## Response
- `object` (string): Always `backup`.
- `id` (string): The backup id (`cbb_…`).
- `bucket_id / project_id` (string): Where it was taken.
- `name` (string): Its name.
- `code_ref` (string | null): The code tree it captured (`null` if the bucket had no code yet).
- `objects` (integer): How many stored zips and assets it covers.
- `files` (integer): Files in the captured code tree.
- `bytes` (integer): Total size of the stored files it covers.
- `created_at` (string): ISO 8601 timestamp.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/backups/BACKUP_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 backup with that id on your account. |
## Example response
```json
{
"object": "backup",
"id": "cbb_h3g7f1d9s5a2q8w4e6r0",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
"name": "Before checkout rewrite",
"code_ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
"objects": 2,
"files": 1284,
"bytes": 131204115,
"created_at": "2026-10-28T14:05:11.482Z"
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/backups/restore
# Restore a backup
> Bring a bucket back to a backup.
`POST https://api.codebuckets.clatterlabs.xyz/v1/backups/{backup_id}/restore` (key permission: `backups:write`)
Puts the backup's code tree back as a **new** version (the current one stays reachable by its ref) and brings back stored files from the backup that were deleted since. By default files added after the backup are kept; send `"objects": "exact"` to hide them too. Recorded as a `backup.restored` event.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `backup_id` (string, required): The backup id (`cbb_…`).
## Body
- `objects` (string, default keep): `keep` leaves newer files in place; `exact` makes the stored files match the backup.
## Response
- `object` (string): `restore`.
- `backup_id / bucket_id` (string): What was restored.
- `code_ref` (string | null): The new current code ref.
- `objects` (object): `{ mode, revived, hidden }`: how many stored files came back or were hidden.
## Example request
```bash
curl -X POST "https://api.codebuckets.clatterlabs.xyz/v1/backups/BACKUP_ID/restore" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-d '{
"objects": "keep"
}'
```
## 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 backup with that id on your account. |
## Example response
```json
{
"object": "restore",
"backup_id": "cbb_h3g7f1d9s5a2q8w4e6r0",
"bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
"code_ref": "3e8d0b7c4a1f9b1f0c5e2a7d43e8b6c1f0a9d2e5",
"objects": {
"mode": "keep",
"revived": 1,
"hidden": 0
}
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/backups/delete
# Delete a backup
> Remove a backup.
`DELETE https://api.codebuckets.clatterlabs.xyz/v1/backups/{backup_id}` (key permission: `backups:write`)
Deletes the backup, which frees its slot on the Free tier. The bucket itself isn't touched.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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
- `backup_id` (string, required): The backup id (`cbb_…`).
## Response
- `object` (string): `backup`.
- `id` (string): The backup id.
- `deleted` (boolean): `true`.
## Example request
```bash
curl -X DELETE "https://api.codebuckets.clatterlabs.xyz/v1/backups/BACKUP_ID" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## 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 backup with that id on your account. |
## Example response
```json
{
"object": "backup",
"id": "cbb_h3g7f1d9s5a2q8w4e6r0",
"deleted": true
}
```
---
Source: https://developers.clatterlabs.com/api-reference/code-buckets/usage
# Get usage
> Tokens this month and storage.
`GET https://api.codebuckets.clatterlabs.xyz/v1/usage` (key permission: `buckets:read`)
Your Code Buckets plan, this month's tokens and your storage. Also works with a key that has only `account:read`.
## Authorizations
- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): 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`.
## Response
- `object` (string): `usage`.
- `plan` (string): `Free`, or unlimited for Clatter Labs team accounts.
- `period` (object): `{ month }`, like `2026-10` (UTC).
- `tokens` (object): `{ used, included, unit }`. `included` is 1,000,000 on Free.
- `storage` (object): `{ projects, buckets, stored_bytes, bucket_limit_bytes, backups_used, backups_included, public_files }`. `public_files` is this month's traffic to your public links: `{ month, requests, bytes, tokens }`.
## Example request
```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/usage" \
-H "Authorization: Bearer $CLATTER_API_KEY" \
-H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```
## Errors
| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key / missing_account_id / account_mismatch` | The key or Account ID is wrong. |
| `403` | `insufficient_scope` | The key needs `buckets:read` or `account:read`. |
## Example response
```json
{
"object": "usage",
"plan": "Free",
"period": {
"month": "2026-10"
},
"tokens": {
"used": 1342,
"included": 1000000,
"unit": "1 per request + 1 per MiB uploaded or downloaded"
},
"storage": {
"projects": 1,
"buckets": 1,
"stored_bytes": 131204115,
"bucket_limit_bytes": 10737418240,
"backups_used": 1,
"backups_included": 1,
"public_files": {
"month": "2026-10",
"requests": 1840,
"bytes": 96468992,
"tokens": 1932
}
}
}
```
---
Source: https://developers.clatterlabs.com/models
# Models
> SuperCosmos 1.1: what it is for, its efforts Flash, Max and Heavy, and the price of every effort per 1M tokens.
**SuperCosmos 1.1** is the model behind everything you build with Clatter Labs. It comes in three **efforts** that trade speed and cost for depth, and every effort has its own price.
- **SuperCosmos 1.1** (Agent API · Model API · Line CLI · Cosmos Agent): The model family behind every Clatter Labs product, tuned for coding-agent work. Efforts: Flash, Max, Heavy. Size: 550B params (55B active). Context window: 1M tokens. From $1.60 in · $3.40 out.
## Size and context window
| Model | Parameters | Active per token | Context window |
| --- | --- | --- | --- |
| SuperCosmos 1.1 | 550B | 55B | 1M tokens (1,048,576) |
SuperCosmos is a mixture-of-experts model: each token runs through only part of the network (the active parameters), which keeps it fast for its size. Efforts share the model's weights and context window. Line CLI compacts a long conversation automatically at about 80% of the window.
## What an effort is
An effort is how much work the model puts into each step: how long it thinks before acting, how carefully it plans and checks, and how many tokens that takes. Higher efforts reason longer and verify more, so they are slower and cost more per token. Pick the lowest effort that does the job, and move up when a task keeps failing its own checks or needs a plan across many files.
- **Agent API**: set `tier` on `POST /v1/runs` (`auto`, `flash`, `max`, `heavy`).
- **Line CLI**: `/effort` picks the effort (or `line -e `).
- **Model API**: each effort is its own model id, like `supercosmos-max` ([Model API](/model-api/overview)).
## SuperCosmos
- **Flash** (Fast): $1.60 input / $3.40 output per 1M tokens. Answers without extended thinking. Quick edits, answers and the everyday steps of an agent loop.
- **Max** (Strong): $1.80 input / $3.80 output per 1M tokens. Thinks before acting. Planning, debugging and multi-file changes.
- **Heavy** (Deliberate): $2.00 input / $4.40 output per 1M tokens. Thinks longest and writes the longest answers. Hard bugs, long builds, deep reasoning.
Model ids are `supercosmos-flash`, `supercosmos-max` and `supercosmos-heavy`. With `auto`, each call is routed and billed at the effort it actually ran on; Agent API runs on `auto` bill as Flash. See the [SuperCosmos overview](/models/overview).
## All prices
| Model | Effort | Input / 1M tokens | Output / 1M tokens | Where |
| --- | --- | --- | --- | --- |
| SuperCosmos 1.1 | Flash | $1.60 | $3.40 | Agent API, Model API, Line CLI, Cosmos Agent |
| SuperCosmos 1.1 | Max | $1.80 | $3.80 | Agent API, Model API, Line CLI, Cosmos Agent |
| SuperCosmos 1.1 | Heavy | $2.00 | $4.40 | Agent API, Model API, Line CLI, Cosmos Agent |
**Long-context input above 262K tokens: 1.5×**: a request whose prompt is over 262K tokens bills its whole input at 1.5× the rate above.
Output includes reasoning tokens. In Line CLI, usage counts toward your [plan](/billing/credits)'s usage limits at the price of the effort each call ran on. Model API and Agent API calls are paid from your credits; Agent API runs also pay for computer time and actions (see [Rates](/billing/rates)).
SuperCosmos reads text. It doesn't take image input.
## Previous models
- **[SuperCosmos 1.0](/models/supercosmos-1-0)**: the previous SuperCosmos version. Its model ids now run SuperCosmos 1.1, at the same prices.
- **[Line Code](/models/line-code)**: retired on Nov 1, 2026. Its ids answer `410 model_retired`. See [Line Code retirement](/models/line-code-retired).
---
Source: https://developers.clatterlabs.com/models/overview
# SuperCosmos 1.1
> SuperCosmos 1.1 by Clatter Labs powers the Agent API, the Model API, Line CLI and Cosmos Agent. Three tiers (efforts in Line CLI) trade speed for depth.
**SuperCosmos 1.1** (Agent API · Line CLI · Cosmos Agent): The model family behind every Clatter Labs product, tuned for coding-agent work. Where: All products. Efforts: Flash, Max, Heavy (Fast, Strong, Deliberate). Size: 550B (55B active). Context window: 1M tokens. From $1.60 in · $3.40 out. Input: Text.
**SuperCosmos by Clatter Labs** is the model family behind every Clatter Labs product. The current version is **SuperCosmos 1.1** (Nov 2, 2026). It is a 550B-parameter mixture-of-experts model (55B active per token) with a 1M-token context window (1,048,576 tokens), and it comes in three tiers that share those weights and that window, each tuned with its own instructions for coding-agent work: look before changing, use tools carefully, plan bigger jobs, verify before reporting, answer briefly.
- **Flash** (Fast): $1.60 input / $3.40 output per 1M tokens. Quick edits, answers and everyday agent steps. No extended thinking.
- **Max** (Strong): $1.80 input / $3.80 output per 1M tokens. Planning, debugging and multi-file changes. Thinks before acting.
- **Heavy** (Deliberate): $2.00 input / $4.40 output per 1M tokens. Hard bugs, long builds, deep reasoning. Thinks longest.
## Compare tiers
| | Flash | Max | Heavy |
| --- | --- | --- | --- |
| Model id | `supercosmos-flash` | `supercosmos-max` | `supercosmos-heavy` |
| Speed | Fastest | Balanced | Slowest |
| Extended thinking | Off | On | On, longest |
| Parameters | 550B (55B active) | 550B (55B active) | 550B (55B active) |
| Context window | 1M tokens | 1M tokens | 1M tokens |
| Input / 1M tokens | $1.60 | $1.80 | $2.00 |
| Output / 1M tokens | $3.40 | $3.80 | $4.40 |
| Long-context input (above 262K tokens) | 1.5× | 1.5× | 1.5× |
Output prices include reasoning tokens.
## Where you choose a tier
| Product | How |
| --- | --- |
| Agent API | `tier` on `POST /v1/runs`: `auto`, `flash`, `max`, `heavy` |
| Model API | The model id: `supercosmos-flash`, `supercosmos-max` or `supercosmos-heavy` ([Model API](/model-api/overview)) |
| Line CLI | `/model` → **SuperCosmos**, then `/effort flash`, `max` or `heavy` (or `auto`, which routes between Flash and Max per step) |
With `auto`, each call is routed and **billed at the tier it actually ran on**. Agent API runs on `auto` bill as Flash.
In Line CLI the tiers are called **efforts** of the SuperCosmos model (Flash, Max, Heavy); prices are the same.
## Previous versions
| Model | Status | |
| --- | --- | --- |
| [SuperCosmos 1.0](/models/supercosmos-1-0) | Previous version | Its model ids now run SuperCosmos 1.1, at the same prices. |
| [Line Code](/models/line-code) | Retired Nov 1, 2026 | Its ids answer `410 model_retired`; Line CLI moves to SuperCosmos automatically. See [Line Code retirement](/models/line-code-retired). |
SuperCosmos reads text. It doesn't take image input.
---
Source: https://developers.clatterlabs.com/models/flash
# SuperCosmos Flash
> The fast tier. Quick edits, answers and the everyday steps of an agent loop.
Flash answers without extended thinking, so each step comes back quickly. It's the right default for high-volume and interactive work.
| | |
| --- | --- |
| Model id | `supercosmos-flash` |
| Model | SuperCosmos: 550B parameters, 55B active per token |
| Context window | 1M tokens (1,048,576) |
| Agent API | `"tier": "flash"` (also what `auto` runs bill as) |
| Input | $1.60 per 1M tokens |
| Output | $3.40 per 1M tokens |
| Long context | Long-context input above 262K tokens: 1.5× |
## Good fits
- Small, well-described changes: rename, fix a type error, add a test
- Scripts and one-off automation
- Answering questions about a codebase
- Fast agent loops where many short steps add up
## Move up when
A task needs a plan across several files, keeps failing its own checks, or the answers miss the point. Try [Max](/models/max).
---
Source: https://developers.clatterlabs.com/models/max
# SuperCosmos Max
> The strong tier. Thinks before acting; built for planning, debugging and multi-file changes.
Max reasons before it acts, which makes it more reliable on work that needs a plan.
| | |
| --- | --- |
| Model id | `supercosmos-max` |
| Model | SuperCosmos: 550B parameters, 55B active per token |
| Context window | 1M tokens (1,048,576) |
| Agent API | `"tier": "max"` |
| Input | $1.80 per 1M tokens |
| Output | $3.80 per 1M tokens |
| Long context | Long-context input above 262K tokens: 1.5× |
## Good fits
- Building a feature end to end
- Debugging from logs and failing tests
- Refactors that touch several files
- Setting up projects, CI and deployments
## Move up when
The problem is genuinely hard: a subtle bug, a large build, or a task where getting it right matters more than speed. Try [Heavy](/models/heavy).
---
Source: https://developers.clatterlabs.com/models/heavy
# SuperCosmos Heavy
> The deliberate tier. Thinks longest and writes the longest answers, for the hardest problems.
Heavy spends the most effort per step. It's slower and costs more, and it's the tier to reach for when the other two can't crack a problem.
| | |
| --- | --- |
| Model id | `supercosmos-heavy` |
| Model | SuperCosmos: 550B parameters, 55B active per token |
| Context window | 1M tokens (1,048,576) |
| Agent API | `"tier": "heavy"` |
| Input | $2.00 per 1M tokens |
| Output | $4.40 per 1M tokens |
| Long context | Long-context input above 262K tokens: 1.5× |
## Good fits
- Hard bugs: race conditions, memory issues, flaky tests
- Large builds and migrations
- Architecture and design reviews
- Tasks where a wrong answer is expensive
Heavy is rarely the right default. Use `auto` or Flash for most runs and send only the hard ones to Heavy.
---
Source: https://developers.clatterlabs.com/models/supercosmos-1-0
# SuperCosmos 1.0
> The previous version of SuperCosmos: 550B parameters (55B active), a 1M-token window and three tiers, Flash, Max and Heavy. SuperCosmos 1.1 replaced it on Nov 2, 2026.
**SuperCosmos 1.0** (Previous version): The model family behind every Clatter Labs product, tuned for coding-agent work. Where: All products. Efforts: Flash, Max, Heavy (Fast, Strong, Deliberate). Size: 550B (55B active). Context window: 1M tokens. From $1.60 in · $3.40 out. Input: Text.
SuperCosmos 1.0 is the previous version of SuperCosmos. Since Nov 2, 2026 the model ids `supercosmos-flash`, `supercosmos-max` and `supercosmos-heavy` run **SuperCosmos 1.1**, at the same prices. See [SuperCosmos 1.1](/models/overview).
**SuperCosmos 1.0** was the first version of SuperCosmos by Clatter Labs, the model family behind every Clatter Labs product. It is a 550B-parameter mixture-of-experts model (55B active per token) with a 1M-token context window (1,048,576 tokens), and it comes in three tiers that share those weights and that window, each tuned with its own instructions for coding-agent work: look before changing, use tools carefully, plan bigger jobs, verify before reporting, answer briefly.
- **Flash** (Fast): $1.60 input / $3.40 output per 1M tokens. Quick edits, answers and everyday agent steps. No extended thinking.
- **Max** (Strong): $1.80 input / $3.80 output per 1M tokens. Planning, debugging and multi-file changes. Thinks before acting.
- **Heavy** (Deliberate): $2.00 input / $4.40 output per 1M tokens. Hard bugs, long builds, deep reasoning. Thinks longest.
## Compare tiers
| | Flash | Max | Heavy |
| --- | --- | --- | --- |
| Model id | `supercosmos-flash` | `supercosmos-max` | `supercosmos-heavy` |
| Speed | Fastest | Balanced | Slowest |
| Extended thinking | Off | On | On, longest |
| Parameters | 550B (55B active) | 550B (55B active) | 550B (55B active) |
| Context window | 1M tokens | 1M tokens | 1M tokens |
| Input / 1M tokens | $1.60 | $1.80 | $2.00 |
| Output / 1M tokens | $3.40 | $3.80 | $4.40 |
| Long-context input (above 262K tokens) | 1.5× | 1.5× | 1.5× |
Output prices include reasoning tokens.
## Where you choose a tier
| Product | How |
| --- | --- |
| Agent API | `tier` on `POST /v1/runs`: `auto`, `flash`, `max`, `heavy` |
| Model API | The model id: `supercosmos-flash`, `supercosmos-max` or `supercosmos-heavy` ([Model API](/model-api/overview)) |
| Line CLI | `/model` → **SuperCosmos**, then `/effort flash`, `max` or `heavy` (or `auto`, which routes between Flash and Max per step) |
With `auto`, each call is routed and **billed at the tier it actually ran on**. Agent API runs on `auto` bill as Flash.
In Line CLI the tiers are called **efforts** of the SuperCosmos model (Flash, Max, Heavy); prices are the same.
## Line Code
Alongside SuperCosmos 1.0, Line CLI and the [Model API](/model-api/overview) offered **[Line Code](/models/line-code)**, Clatter Labs' coding model (retired Nov 1, 2026): efforts **Fast** ($1.15 / $1.60), **Ultra** ($1.25 / $1.90) and **Ultra Fast** ($1.40 / $2.20) per 1M input / output tokens. Current prices are on [Models](/models).
SuperCosmos reads text. It doesn't take image input.
---
Source: https://developers.clatterlabs.com/models/line-code
# Line Code
> Retired on Nov 1, 2026 and replaced by SuperCosmos 1.1. Line CLI's former coding model: efforts Fast, Ultra and Ultra Fast, about 428B parameters (23B active), 256K-token window.
**Line Code** (Retired · Nov 1, 2026): Smart, fast and disciplined: fast by default, deep reasoning only when a step needs it. Where: Line CLI · Model API. Efforts: Fast, Ultra, Ultra Fast (Default, Careful, Best quality). Size: ~428B (23B active). Context window: 256K tokens. From $1.15 in · $1.60 out. Input: Text.
**Retired on Nov 1, 2026, replaced by SuperCosmos 1.1.** The ids `line-code`, `line-code-fast`, `line-code-ultra` and `line-code-ultra-fast` now answer `410 model_retired` and are never billed, and Line CLI moves to SuperCosmos automatically. This page keeps Line Code's documentation for reference. To switch, see [Line Code retirement](/models/line-code-retired) and [SuperCosmos 1.1](/models/overview).
**Line Code** is Line CLI's own coding model: smart, fast and disciplined. It is available in **Line CLI** (v5 beta and later) and the **[Model API](/model-api/overview)** (model ids `line-code-fast`, `line-code-ultra` and `line-code-ultra-fast`), not in the Agent API or Cosmos Agent, and it runs on its own capacity, separate from SuperCosmos. It is a mixture-of-experts model with about 428B parameters (23B active per token) and a 256K-token context window (262,144 tokens); all three efforts share them.
It is fast by default and thinks harder only when a step needs it: a rename or a one-line fix goes straight to the tools, while a design decision, an unclear failing test, concurrency or security gets real reasoning before any file is touched. It verifies its changes with your project's own checks and never claims a result it didn't see.
```bash
line --model line-code # this run
line --model line-code --effort ultra-fast # this run, with an effort
```
In the TUI: `/model` → **Line Code**, then pick an effort, or switch any time with `/effort`.
## Efforts
| Effort | What it does | Use it for |
| --- | --- | --- |
| **Fast** (default) | Acts quickly and thinks only as much as each step needs | Everyday edits, fixes, tool loops |
| **Ultra** | Thinks deeply, plans with a to-do list, checks edge cases and reviews its own diff | Hard bugs, refactors, anything you want done carefully |
| **Ultra Fast** | The most accurate and the fastest: deep reasoning plus parallel (hedged) generation, front-loaded context and self-verification | When both quality and speed matter more than cost |
Switch with `/effort fast`, `/effort ultra` or `/effort ultra-fast` (or the picker). The effort is saved for your next sessions.
## Pricing
Each effort has its own price, per 1M tokens:
- **Fast** (Default): $1.15 input / $1.60 output per 1M tokens. Everyday edits, fixes and tool loops.
- **Ultra** (Careful): $1.25 input / $1.90 output per 1M tokens. Hard bugs, refactors, anything you want done carefully.
- **Ultra Fast** (Best quality): $1.40 input / $2.20 output per 1M tokens. When both quality and speed matter more than cost. Uses about 30× the tokens of Fast on the same task.
| Effort | Input / 1M tokens | Output / 1M tokens |
| --- | --- | --- |
| Fast | $1.15 | $1.60 |
| Ultra | $1.25 | $1.90 |
| Ultra Fast | $1.40 | $2.20 |
Output includes reasoning tokens. **Ultra Fast uses by far the most tokens** (about 30× Fast on the same task): it thinks longer and sends each step twice in parallel to take the faster answer, so the input of that second copy is counted too. In Line CLI it counts toward your [plan](/billing/credits)'s limits (every effort on every plan); through the Model API it is paid from credits. Each call is priced at the effort it ran on and shows in the Console as Line Code. All model prices are on [Models](/models).
## Line Code or SuperCosmos?
| | Line Code | SuperCosmos |
| --- | --- | --- |
| Where | Line CLI, Model API | Line CLI, Agent API, Model API, Cosmos Agent |
| Efforts | Fast, Ultra, Ultra Fast | Flash, Max, Heavy |
| Parameters | ~428B (23B active) | 550B (55B active) |
| Context window | 256K tokens | 1M tokens |
| Price / 1M in · out | from $1.15 · $1.60 (Fast) to $1.40 · $2.20 (Ultra Fast) | from $1.60 · $3.40 (Flash) to $2.00 · $4.40 (Heavy) |
| Capacity | Its own | Shared SuperCosmos capacity |
Both are served through the Line API; no model keys ever reach your machine. See [SuperCosmos models](/models/overview).
Line Code reads text. It doesn't take image input.
---
Source: https://developers.clatterlabs.com/changelog
# Changelog
> New releases and improvements across Clatter Labs developer products.
### SuperCosmos 1.1
- **SuperCosmos 1.1** is the model behind every Clatter Labs product: 550B parameters (55B active), a 1M-token context window, efforts Flash, Max and Heavy. Model ids and prices are unchanged: Flash $1.60 / $3.40, Max $1.80 / $3.80, Heavy $2.00 / $4.40 per 1M input / output tokens. `GET /v1/models` reports `version: "1.1"`. See [SuperCosmos models](/models/overview).
- **Line Code is retired.** Its Model API ids answer `410 model_retired` and are never billed; Line CLI moves to SuperCosmos automatically. See [Line Code retirement](/models/line-code-retired).
- **Line CLI 0.9.0-beta** runs on SuperCosmos 1.1 only. Line Code is gone from `/model`, `--model` and `--effort`; a saved Line Code setting moves to SuperCosmos once (Fast → Flash, Ultra → Max, Ultra Fast → Heavy), and scripts that pass `-m line-code` keep working with a notice. Update with `line update` or reinstall: `curl -fsSL https://install.clatterlabs.xyz/line | sh`.
- **Abuse policy.** Insulting or cursing at the assistant earns a warning, and a second time within 30 days pauses the account for 24 hours (`403 account_suspended`). On the Model API and Agent API the key owner's account is responsible for its end users' text. See the [Abuse policy](/policies/abuse).
### Line CLI v0.7.1-beta
Line now uses the new plans and prices.
- `/cost`, the effort picker and the status bar use the new list prices per 1M input / output tokens: SuperCosmos Flash $1.60 / $3.40, Max $1.80 / $3.80, Heavy $2.00 / $4.40 (input above 262K tokens of context bills 1.5×); Line Code Fast $1.15 / $1.60, Ultra $1.25 / $1.90, Ultra Fast $1.40 / $2.20.
- `/usage` shows your plan's usage as % used with the reset time (usage window and week on paid plans, the month on Free), plus your API credits.
Update with `line update`. See [Line CLI](/line/overview).
### New plans and model prices
- **Plans**: Free, Developer ($15/month), Plus ($25), Pro ($50), Max ($100) and Ultra ($200). Every plan includes every model and every tool across Line CLI, Cosmos Agent (Telegram included) and Code Buckets. Paid plans reset in short usage windows and weekly; Free has a monthly allowance. Billing shows % used and reset times. See [Plans and credits](/billing/credits).
- **API pay as you go on every plan**: the Model API and the Agent API are paid from credits; top up any amount from $1 to $800.
- **Model prices** per 1M input / output tokens: SuperCosmos Flash $1.60 / $3.40, Max $1.80 / $3.80, Heavy $2.00 / $4.40; Line Code Fast $1.15 / $1.60, Ultra $1.25 / $1.90, Ultra Fast $1.40 / $2.20. SuperCosmos long-context input above 262K tokens: 1.5×. See [Models](/models).
- New error codes for app usage: `window_limit_reached`, `weekly_limit_reached`, `monthly_limit_reached` (HTTP 429). `plan_required` and `model_not_in_plan` are gone.
### Line CLI v7 beta
Line is now a local-first agent: sub-agents with full tools that edit in parallel safely, background shells, MCP, hooks, a repo map, per-model context windows and usage, and native Arabic.
- **Parallel sub-agents with full tools**: besides read-only explore, research and review, general sub-agents edit files and run commands under your permission mode. Per-file locks, read-before-edit and conflict checks keep parallel edits from overwriting each other. The **Agents panel** shows them live; `/agents` lists runs and reports.
- **New tools**: background shells (`bash_output`, `kill_shell`, `/bashes`), `web_search`, `notebook_edit`, read-only `git`, `diagnostics` and a tree-sitter **repo map**.
- **MCP** servers (`/mcp`, `line mcp`), **hooks** (`/hooks`) and **LINE.md / AGENTS.md** project instructions.
- **See your changes**: `/diff` (unified or `/diff split`) and `/files`.
- **Usage and context**: `/usage` with your plan's daily and weekly limits, credits and per-model tokens; a live context meter, `/context`, and auto-compact at about 80% of the model's real context window.
- **Model size and context window** in `/model` and on [Models](/models): SuperCosmos 550B parameters (55B active), 1M-token context; Line Code ~428B (23B active), 256K-token context.
- **Arabic, natively**: right-to-left text is joined, ordered and right-aligned in answers and in the input (`/rtl`).
- **Cosmos delegation removed**: `/delegate`, `/conversations`, `/tasks` and `/link` are gone; sub-agents run the work locally.
- In our task-12 eval (parallel modules with sub-agents, SuperCosmos Flash), 0.6.0-beta passed in 672 s and 0.7.0-beta in 516 s.
Update with `line update`. See [Line CLI](/line/overview) and [Commands](/line/commands).
### One plan story, credit packs, Agent API generally available
- **Every account has a plan.** Free, Starter ($5), Plus ($20), Pro ($50) and Ultra ($200) each have a **daily** and a **weekly** usage limit for app usage (Line CLI, Cosmos Agent apps). The Console shows *Daily limit usage* and *Weekly limit usage* under **Billing**.
- **API calls are pay as you go from credits.** The Model API and the Agent API never use your plan's limits. New accounts start with **$5 of free credit** (replacing the $20 grant and the separate $5 Model API trial), and credit packs ($10 to $100) are in **Billing › Credits**.
- **Agent API is generally available** with Plus, Pro and Ultra.
- **Ultra API access quota:** move part of Ultra's $200 cycle value into API credits yourself.
- **Code Buckets storage per plan:** 10 GB Free, 50 GB Starter, 200 GB Plus, 500 GB Pro, 2 TB Ultra.
See [Plans and credits](/billing/credits).
### A new look for the docs
- Section tabs sit in the top bar, the sidebar is calmer, and every page has an **On this page** rail with **Copy page** and **View as Markdown**.
- Search (**⌘K**, Ctrl+K on Windows and Linux) opens a wider dialog with filters for Documentation, API reference, Models and Changelog.
- The **Models** tab is reordered: Overview, then SuperCosmos (Overview, Flash, Max, Heavy), then Line Code.
- Light and dark themes and the phone layout were redone to match.
### Line CLI v6 beta
Long tasks now finish: streams no longer stop mid-step, Line Code stops hitting "model busy" storms, and the agent keeps working until the task is done and checked.
- **Streams run to the end**: long steps (big edits, deep thinking) are no longer cut off partway; Line also detects a cut stream and redoes the step instead of treating it as an empty answer.
- **No more "model busy" storms on Line Code**: the Line API paces requests to stay under capacity instead of retrying into errors. Busy or interrupted steps are retried patiently (up to 8 minutes per step) with the reason shown in the status line.
- **Auto-continue**: if the model stops before the work is done (open to-do items, "now I'll run the tests" with no tool call, an empty reply, edits it never checked), Line tells it to keep going, and asks it to run the tests or build before its final answer.
- **Auto-compact**: long tasks summarize their older steps when the context fills up, so they keep their plan and don't overflow.
- **Fewer failed edits**: indentation slips are matched automatically, and a failed edit shows the closest lines of the file.
- **[Line Code](/models/line-code) prices per effort**: Fast $0.80 / $2.31, Ultra $2.93 / $9.30, Ultra Fast $5.00 / $12.00 per 1M input / output tokens; `/cost` uses the effort you ran on.
Update with `line update`.
### Line CLI v5 beta
- **[Line Code](/models/line-code)**: Line's own coding model (Line CLI only), with efforts **Fast** (default), **Ultra** and **Ultra Fast** (most accurate and fastest, uses the most tokens). $0.80 input / $2.31 output per 1M tokens.
- **Efforts**: SuperCosmos is one model with efforts Flash, Max and Heavy. `/model` picks the model, `/effort` the effort; `line -m line-code -e ultra` for one run.
- **Busy models no longer fail your turn**: the Line API retries with backoff (honouring Retry-After) and hedges slow requests; Line waits, shows "Model busy · retrying in Ns", and redoes a step whose stream broke.
- **Sub-agents**: the agent runs read-only local sub-agents in parallel to explore, research or review.
- **Plan mode and permission modes** (Shift+Tab: ask, accept edits, auto, plan), **/undo** and **/rewind** for file changes, **@file** mentions, a live to-do panel, `/context`.
- **TUI**: mouse-wheel and PgUp/PgDn scrolling that stays put while output streams; the status bar shows files created, files changed and lines added/removed next to the token count.
### Docs focused on what you build with
- The docs now cover only the Cosmos Agent API and Line CLI, with everything they need: API keys, Account ID, tiers and prices, credits, errors and limits.
### New developer docs
The docs moved to a new home with search, an API reference with a live **Try it** playground for every Agent API endpoint, and guides for the Cosmos Agent API, Line CLI, SuperCosmos tiers and credits.
- Agent API docs moved here from the Console.
- Every page can be copied as Markdown, and the whole site is available at [/llms.txt](/llms.txt) for AI tools.
### Agent API
Run Cosmos Agent from any language at `https://api.agent.clatterlabs.xyz`: create runs, stream their events, read results and files, cancel, and check your balance. See the [API reference](/api-reference/introduction).
- Keys (`clsk_…`) with permissions and per-key rate limits, made in the Console.
- Every keyed request also sends your Account ID in `X-Clatter-Account`.
- Runs take a `tier`: `auto`, `flash`, `max` or `heavy`.
### Clatter Labs Console
[console.clatterlabs.com](https://console.clatterlabs.com): API keys, models, logs, usage, credits and billing.
### Credits
One balance per account, shared by the Agent API, Line CLI and Cosmos Agent, with $20 free for new accounts. Per-tier SuperCosmos pricing: Flash $0.75 / $2.50, Max $3.00 / $5.00, Heavy $6.00 / $11.51 per 1M input / output tokens. See [Rates](/billing/rates).
### Line CLI v4 beta
- **SuperCosmos only**: Flash, Max and Heavy, each with its own tuned instructions. Saved choices of removed models switch to `auto`.
- **Skills**: SKILL.md folders the agent can use, install and create, always with your approval. See [Skills](/line/skills).
- **Plugins**: tools, commands, hooks and skills in a `plugin.json`, off until you enable them. See [Plugins](/line/plugins).
- **New tools**: `multi_edit`, `delete_file`, `move_file`, `web_fetch`, `todo_write`, `delegate`, `delegation_status`.
- **Cosmos link** with short-lived, scoped permissions you can revoke (removed in v0.7.0-beta).
- **Security**: secret files always ask; read-only commands limited to the project; commands no longer inherit `LINE_TOKEN`.
### Sub-agents and conversations
- `/delegate ` hands work to a Cosmos sub-agent in the cloud.
- `/conversations` lists sub-agent threads; `/conversations ` continues one and follows the reply live.
### Long tasks that finish
- Big files and many-file builds no longer cut off: the API keeps the connection alive while a large change is written.
- Stalled steps resume on their own; big files are written in parts with the new `append_file` tool; replies up to 32k tokens.
- Flash, Max and Heavy run on dedicated capacity.