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