KhotanalphaMarkdown

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:

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 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:

Never commit a key. See authentication for how keys are scoped, stored, and managed, or 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:

{ "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 for retries, idempotency, and the rest of the shared contract, or 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:

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:

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):

Responses:

CLI: khotan auth login

Resources