> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# HTTP API

Khotan exposes a REST API at `/api/v1`. It is the surface the `khotan` CLI wraps — the CLI adds no capability the API lacks, so anything you can do at the terminal you can do over HTTP. These pages are generated from the OpenAPI document, so they cannot drift from the routes that serve them.

`Khotan API` v1.0.0 · 168 operations.

## Base URL

Every request goes to `https://app.khotan.com`:

```bash
curl https://app.khotan.com/api/v1/apps \
  -H "Authorization: Bearer $KHOTAN_API_KEY"
```

There is no per-workspace API host. A key carries its own organization and no operation reads the request host, so the base URL never varies by account or workspace.

The machine-readable document is at [`/api/v1/openapi.json`](https://app.khotan.com/api/v1/openapi.json) on the same origin, and is also published on this site for reading without an account. Generate a client from the document rather than scraping these pages; they summarize each operation and omit nested response schemas.

## Authentication

Every operation except the ones marked otherwise requires an organization-scoped API key. Keys are minted in workspace settings, or by exchanging email and password via `POST /api/v1/api-keys`. A key carries its organization, so there is no account or workspace parameter on any request.

Send the key one of two ways:

- `Authorization: Bearer <key>` — Organization-scoped API key sent as `Authorization: Bearer <key>`.
- `x-api-key: <key>` — Organization-scoped API key sent as the `x-api-key` header.

Never commit a key. See [authentication](/api/auth/) for how keys are scoped, stored, and managed, or [CLI auth](/cli/auth/) for how the CLI selects between them.

## Errors and rate limits

Errors share one envelope, so a client can branch on `error.code` without special-casing routes:

```json
{ "error": { "code": "not_found", "message": "App not found.", "details": {} } }
```

`401` means the key is missing or invalid, `403` means the key's organization cannot reach the resource, `404` means it does not exist, `400` means the request failed validation, and `429` means a rate limit was exceeded. Rate limits are applied per key; back off and retry on `429`, which carries a `Retry-After` header.

See [conventions](/api/conventions/) for retries, idempotency, and the rest of the shared contract, or [CLI errors](/cli/errors/) for how the CLI surfaces these.

## Core operations

Start here: confirm the API is reachable, mint a key, and check which organization that key belongs to.

### GET /api/v1/health

Service readiness probe

Confirms the service is up and can reach its database.

Auth: none — this operation is callable without a key.

Operation ID: `getHealth`

Responses:
- `200` — The service is healthy.
- `429` — Too many requests; retry after the indicated delay.
- `503` — The service cannot reach its database.

### GET /api/v1/me

Identify the caller

Returns the organization, role, and key id resolved from the API key.

Auth: API key required.

Operation ID: `getCurrentApiPrincipal`

Responses:
- `200` — The authenticated principal.
- `401` — Authentication is missing or invalid.
- `429` — Too many requests; retry after the indicated delay.

CLI: `khotan whoami`

### POST /api/v1/api-keys

Exchange credentials for an API key

Authenticates with email + password and mints an organization-scoped API key. Strictly rate limited.

Auth: none — this operation is callable without a key.

Operation ID: `createApiKeyFromCredentials`

Request body (`application/json`, required):
- `email` (string, required)
- `password` (string, required)
- `organizationId` (string, required)
- `name` (string, optional)
- `role` ("owner" | "admin" | "developer" | "member", optional)
- `expiresInDays` (integer, optional)

Responses:
- `201` — The minted API key (the secret is returned only once).
- `400` — The request was malformed or failed validation.
- `401` — Authentication is missing or invalid.
- `403` — The caller is not permitted to perform this action.
- `429` — Too many requests; retry after the indicated delay.

CLI: `khotan auth login`

## Resources

- [Apps](/api/apps/) — 29 operations.
- [Pipelines](/api/pipelines/) — 27 operations.
- [Files](/api/files/) — 9 operations.
- [Context](/api/context/) — 16 operations.
- [Integrations](/api/integrations/) — 6 operations.
- [Databases](/api/databases/) — 16 operations.
- [Redis Databases](/api/redis-databases/) — 6 operations.
- [SQLite Databases](/api/sqlite-databases/) — 5 operations.
- [Buckets](/api/buckets/) — 7 operations.
- [Folders](/api/folders/) — 4 operations.
- [Projects](/api/projects/) — 26 operations.
- [AI capture](/api/ai-capture/) — 2 operations.
- [Implementation traces](/api/implementation-traces/) — 1 operation.
- [Organization](/api/organization/) — 3 operations.
- [Inbox](/api/inbox/) — 7 operations.
- [Feedback](/api/feedback/) — 1 operation.

<!-- generated from the /api/v1 OpenAPI spec v1.0.0 (adapter 0.10.0); do not edit by hand -->