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:

Session tokens — the short-lived identity token your signed-in session uses (this is what the console sends).
API tokens — kc_-prefixed machine tokens minted from a service account, for CI and agents. See API tokens & service accounts.

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 and the Service object.