# Koo API

The Koo REST API gives you programmatic access to everything the console does: projects,
environments, services, variables, volumes, deployments, domains, notifications, and
observability.

## Base URL

```text
https://api.koo.io
```

All requests and responses are JSON with camelCase field names. There is no version prefix — the
surface is stable and additive.

## Authentication

Every request carries a bearer token:

```bash
curl https://api.koo.io/whoami \
  -H "Authorization: Bearer <token>"
```

Two token kinds:

- 
-

Both kinds work on every endpoint except the user-only `/me` surface, which answers session
tokens alone. Make `GET /whoami` the first call with any credential: it returns the principal
you are acting as — and, for an API token, the account and role it is confined to.

## Errors

Errors use one stable envelope:

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Your plan does not allow another service of this size.",
    "requestId": "..."
  }
}
```

The `code` is stable and machine-matchable; `message` is human-readable and may change. Some
codes add a `details` object with structured context; otherwise the field is omitted. Include
the `requestId` when you contact support.

## Pagination

List endpoints use cursor pagination: pass `?limit=` and the `cursor` from the previous page;
responses return `{ "data": [...], "page": { "nextCursor": "...", "hasMore": true } }`.

## Idempotency

Creating `POST` requests accept an `Idempotency-Key` header — retries with the same key return
the original result instead of creating twice.

## Explore the reference

Browse the object models and endpoint groups in the sidebar, or start with the
[Environment object](/api/objects/environment) and the [Service object](/api/objects/service).