# API conventions

The rules every call to kosem's API follows, including its base URL, authentication, resource names, pages, errors and retries.

Every operation in the [API reference](/reference/api) follows these conventions.

## Base URL [#base-url]

```text
https://api.kosem.ai
```

Every path starts with `/v1/`. Requests and responses are JSON.

## Authentication [#authentication]

Send an API key as a bearer token:

```http
Authorization: Bearer kosem_sk_…
```

API keys belong to service accounts. [Call the API](/get-started/call-the-api) shows how to create one. A request without valid credentials fails with `unauthenticated` (401).

## Resource names [#resource-names]

| Resource                        | Name                                                                  |
| ------------------------------- | --------------------------------------------------------------------- |
| Organization                    | `organizations/org_…`                                                 |
| Project                         | `projects/prj_…`                                                      |
| In a project                    | `projects/prj_…/agents/ags_…`                                         |
| In an organization or a project | `organizations/org_…/secrets/sec_…` or `projects/prj_…/secrets/sec_…` |

Paths take IDs, never slugs. `GET /v1/organizations/lookup` and `GET /v1/projects/lookup` find an ID from a slug. [Organizations and projects](/concepts/organizations-and-projects#resource-names) explains the names.

## Standard methods [#standard-methods]

| Method | HTTP                   | Example                                      |
| ------ | ---------------------- | -------------------------------------------- |
| List   | `GET` on a collection  | `GET /v1/projects/{project}/agents`          |
| Get    | `GET` on a resource    | `GET /v1/projects/{project}`                 |
| Create | `POST` on a collection | `POST /v1/projects`                          |
| Update | `PATCH` on a resource  | `PATCH /v1/projects/{project}`               |
| Delete | `DELETE` on a resource | `DELETE /v1/projects/{project}/sites/{site}` |

Other actions have paths of their own, such as `/v1/projects/{project}/iam-policy`.

## Pages [#pages]

List methods return one page at a time.

| Field           | In       | Meaning                                                            |
| --------------- | -------- | ------------------------------------------------------------------ |
| `pageSize`      | Query    | How many to return. Each list method says its default and maximum. |
| `pageToken`     | Query    | The `nextPageToken` of the previous page.                          |
| `nextPageToken` | Response | The token for the next page. It's empty on the last page.          |

Lists return only what the caller can see.

## Lists across projects [#lists-across-projects]

To list across an organization's projects, write `-` for the project and filter by the organization:

```sh
export KOSEM_API_KEY='kosem_sk_…'
export KOSEM_ORG='org_01m5r8w2k3e9vbt6g0d4x7qz1h'

curl -s -G "https://api.kosem.ai/v1/projects/-/serviceAccounts" \
  -H "Authorization: Bearer $KOSEM_API_KEY" \
  --data-urlencode "filter=organization = \"organizations/$KOSEM_ORG\""
```

## Errors [#errors]

A failed call answers with an HTTP status and a problem document, as RFC 9457 defines it, of type `application/problem+json`:

```json
{
  "status": 429,
  "code": "resource_exhausted",
  "detail": "…",
  "domain": "billing.kosem.ai",
  "reason": "CREDITS_EXHAUSTED",
  "metadata": { "sku": "…" }
}
```

| Field        | Always | Meaning                                                                   |
| ------------ | ------ | ------------------------------------------------------------------------- |
| `status`     | Yes    | The HTTP status.                                                          |
| `code`       | Yes    | What went wrong, from the codes below.                                    |
| `detail`     | No     | What went wrong, for people. It can change: don't match on it.            |
| `reason`     | No     | Why, for programs to tell failures apart by, such as `CREDITS_EXHAUSTED`. |
| `domain`     | No     | The service the reason belongs to, such as `billing.kosem.ai`.            |
| `metadata`   | No     | What the reason concerns, such as the quota that was exceeded.            |
| `errors`     | No     | The parts of the request that are invalid.                                |
| `retryAfter` | No     | The seconds to wait before trying again, when kosem knows.                |

Match on `reason` and `domain` to handle a particular failure. kosem never renames a reason. The API reference lists every reason, with what it means, under the error schema's `reason`.

### Codes [#codes]

| Code                  | HTTP | Meaning                                                              |
| --------------------- | ---- | -------------------------------------------------------------------- |
| `invalid_argument`    | 400  | The request is invalid. `errors` says which parts.                   |
| `failed_precondition` | 400  | The request is valid, but the resource isn't in a state to allow it. |
| `out_of_range`        | 400  | A value is past the range the operation takes.                       |
| `unauthenticated`     | 401  | The request has no valid credentials.                                |
| `permission_denied`   | 403  | The caller doesn't have permission, or the resource doesn't exist.   |
| `not_found`           | 404  | The resource doesn't exist.                                          |
| `already_exists`      | 409  | A resource with that name or alias already exists.                   |
| `aborted`             | 409  | The request conflicted with another change. Read again and retry.    |
| `resource_exhausted`  | 429  | A quota, a rate limit or the organization's credits ran out.         |
| `canceled`            | 499  | The caller canceled the request.                                     |
| `internal`            | 500  | kosem failed. Retry later.                                           |
| `unknown`             | 500  | kosem failed for a reason it doesn't know.                           |
| `data_loss`           | 500  | Data was lost or corrupted.                                          |
| `unimplemented`       | 501  | The operation isn't available.                                       |
| `unavailable`         | 503  | kosem is unavailable for a moment. Retry later.                      |
| `deadline_exceeded`   | 504  | The request took too long.                                           |

kosem answers `permission_denied` for a resource you can't see whether or not it exists, so that nobody learns what exists by asking.

## Retries [#retries]

When kosem knows when a request can succeed, such as after a rate limit, it says so in seconds in the `Retry-After` header and in the problem's `retryAfter`. Wait at least that long before trying again.

## Access policies [#access-policies]

Resources that have their own access policy, such as projects, have an `iam-policy` path. A policy you read has an `etag`: send it back when you set the policy, and kosem refuses the change if someone changed the policy in the meantime.

## Streams [#streams]

Some operations stream server-sent events, such as following an agent while it works. A stream that fails after it started ends with an `error` event.
