API overview and authentication

Base URL, the three credentials, CORS, request ids, and the error envelope every endpoint uses.

Base URL: https://api.kletso.ai. All bodies are JSON. Every response carries a kletso-request-id header (req_…); quote it when you report a problem.

Credentials

Credential	Header	Used for
Publishable key `kl_pub_…`	`Authorization: Bearer kl_pub_…`	`POST /v1/sessions`, `GET /v1/agents/:id`
Secret key `kl_sec_…`	`Authorization: Bearer kl_sec_…`	The above plus `POST /v1/notifications`
Session token `kst_…`	`Authorization: Bearer kst_…`	Everything under `/v1/sessions/current`, `/v1/conversations`, `/v1/events`, and the first realtime frame
End-user JWT	`X-Kletso-User-Token: <jwt>`	Optional on `POST /v1/sessions`, messages, actions and the realtime upgrade; identifies a signed-in user

The key you use selects the environment (development or production). Session tokens are Ed25519-signed, live one hour, and can be refreshed up to 24 hours after expiry. The verification key is published at GET /.well-known/kletso.json.

Discovery and health

GET /health                      → { "ok": true, "service": "kletso-api" }
GET /.well-known/kletso.json     → { "issuer", "sessionTokenKeys": [jwk], "kid", "realtime": "wss://api.kletso.ai/v1/realtime" }

CORS

/v1/* allows any origin with Authorization, Content-Type, Accept, Cache-Control and X-Kletso-User-Token headers, methods GET, POST, PUT, PATCH, DELETE, OPTIONS, and exposes kletso-request-id and retry-after. Preflights answer 204.

Errors

{ "error": { "code": "invalid_request", "message": "clientId is required", "requestId": "req_01J8…" } }

Code	HTTP
`invalid_request`	400
`unauthorized`, `token_expired`	401
`forbidden`	403
`not_found`	404
`conflict`	409
`rate_limited`, `quota_exceeded`	429 (with `retry-after` seconds)
`provider_error`, `tool_error`	502
`workflow_error`, `internal`	500

Inside realtime error frames the same codes appear with retryable and retryAfterMs.

Rate limits

30 user messages per minute per end user. Over the limit the runtime answers with a rate_limited frame on the socket. Trigger rules have their own per-user frequency caps.

Endpoints

Group	Page
Sessions, context, push tokens	Sessions
Conversations, messages, actions, events, SSE	Conversations
Realtime WebSocket	Realtime frames
App events → triggers	App events
Server-sent notifications	Notifications
Agent info	Agents
Demo backend	Demo backend