Skip to content
Kairos

REST API

OpenAPI 3.1.0, Kairos 0.21.0.

Every endpoint is served under the tenant resolved from the request host and requires a bearer token; see Configuration for how a deployment resolves both. The live spec is at /api/openapi.json.

A write can be complete when its answer does not get to the client (a timeout, an upgrade). Some routes take an optional Idempotency-Key header, and each of these routes lists it. The key has 8 to 128 characters: letters, digits, ., _, : and -. A UUID is a good key.

Send a new key with each new request, and the same key when you retry it. The key belongs to the person and the agent key. A second request with the same key in 24 hours writes nothing. Its answer has the status and the body of the first answer, and the header Idempotent-Replayed: true.

The server refuses the same key with a different route, path or body with 409 REQUEST_KEY_REUSED. A refused request keeps no key, so its retry runs again. The MCP request_key uses the same keys (KAIROS-A-0065).

This page is generated from that spec, so it cannot drift from the router — but it describes only what exists. For how to do something, see the how-to guides; for why the API is shaped this way, see the explanation pages.

Contents

Section titled “Contents”
  • Work items — The five entity families. Every one has the same shape — list, get, create, update, delete — and the same optimistic-concurrency contract on update (KAIROS-A-0004): submit the version you read, and a concurrent edit gets 409 with the current entity in details.current. A write to a claimed task by a different person gets the header Kairos-Warning: <code> claimed by <name> since <time> (KAIROS-T-0359). A task with open blockers can move into a claims column or a done column. That answer gets the header Kairos-Warning: <code> moved into <column>, blocked by <blocker> (open) (KAIROS-T-0565).
  • Across any work item — Operations addressed by {entity_type} and a short code, so they work uniformly across the five families.
  • Boards and teams — Board configuration, membership, the team structures that own boards, and the grants of manage_structure (KAIROS-T-0337).
  • Execution scope — Repositories as first-class execution scope (KAIROS-A-0019) and the git forges behind them.
  • Tenant configuration — Org-admin surfaces: the metadata and template definitions that shape what work items can carry.
  • Machine access — Agent keys of a person, service accounts and their API keys, and the SCIM tokens for directory sync.
  • The deployment itself — Activity, administration, and what the deployment reports about itself.
  • Signing in — Sessions, and local password accounts (KAIROS-I-0018). /api/login and /api/local-accounts are only on a deployment with KAIROS_LOCAL_AUTH on. /api/session and /api/logout are on each deployment (KAIROS-T-0364). /api/login and /api/logout are unauthenticated by nature. Everything under /api/local-accounts is org-admin only, including the reads: a list of somebody’s live sessions is a security surface rather than work content.
  • Schemas — the wire shapes that the operations above reference.