# API overview

The Koo API is how the console, the SDKs, and your own tools talk to Koo. Everything you can do in the console — create [apps and services](/docs/apps/apps-and-services), trigger deployments, read logs — goes through the same API.

This page covers the conventions that apply to every endpoint. For the endpoint-by-endpoint reference, see [the API reference](/api).

## Base URL & format

All requests go to:

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

- 
- 
-

## Authentication

Authenticate every request with a bearer token:

```text
Authorization: Bearer <token>
```

There are two kinds of token:

- 
-

Public endpoints — discovery, public profiles, and public app pages — need no authentication.

## Errors

Every error response uses the same envelope:

```json
{
  "error": {
    "code": "not_found",
    "message": "Service not found.",
    "details": null,
    "requestId": "..."
  }
}
```

`code` is a stable, machine-readable enum — branch on it in your code. `message` is for humans and may change without notice; never parse it. `details` carries structured context for some codes, such as the failing fields on a validation error.

Common codes:

> **Note:**
>
> Include the `requestId` from the error envelope when you [contact support](https://koo.io/support) — it lets us find the exact request in our logs.

## Pagination

List endpoints are cursor-based. Pass `limit` and `cursor` as query parameters; the response wraps results in `data` and a `page` object:

```json
{
  "data": [],
  "page": {
    "nextCursor": "...",
    "hasMore": true
  }
}
```

To fetch the next page, pass `page.nextCursor` as the `cursor` parameter. Cursors are opaque — store and replay them, but don't construct or decode them. When `hasMore` is `false`, you've reached the end.

## Idempotency

POST endpoints that create resources honor an `Idempotency-Key` header. Send a unique key (a UUID works well) with each create; if the request is retried — after a timeout, say — the same key returns the original result instead of creating a duplicate.

## Rate limits

Two distinct limits can reject a request, and they call for different fixes:

- 
-

## Explore the reference

The [API reference](/api) documents every endpoint, generated from the same definitions the API exposes. Good starting points:

- 
- 
- 
-