# 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.

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