Quickstart

Open the Console and copy your Account ID

Sign in to the Console 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.

Create an API 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.

export CLATTER_API_KEY="clsk_..."          # Console › API keys
export CLATTER_ACCOUNT_ID="CL-XXXXXXXX"    # Console › Settings

Start a run

Send Cosmos your instructions. The API answers 201 right away with the run.

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"
  }'

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"])

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);

Watch it work

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.

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"

Get the result

Fetch the run any time for its output, the files it saved and its token usage.

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"