Skip to content
Kairos

Machine access

Agent keys of a person, service accounts and their API keys, and the SCIM tokens for directory sync.

me

Section titled “me”

GET /api/items/{short_code}/watch

Section titled “GET /api/items/{short_code}/watch”

The watch of the caller on the item.

Parameter In Required Type Description
short_code path yes string The item
Response Body Meaning
200 WatchState Whether the caller watches the item, and with its children
403 ErrorEnvelope The caller is a service account
404 ErrorEnvelope No item has the short code

PUT /api/items/{short_code}/watch

Section titled “PUT /api/items/{short_code}/watch”

Watch the item. A coarse change of the item makes a watch notification for the caller: moved, edited, note added, done. A change that the caller made makes none. With with_children: true, a change of a child of the item makes one too. A second PUT changes with_children.

Parameter In Required Type Description
short_code path yes string The item

Request body (required): application/json, WatchRequest

Response Body Meaning
200 WatchState The watch after the change
403 ErrorEnvelope The caller is a service account
404 ErrorEnvelope No item has the short code, the code is retired, or the item is archived

DELETE /api/items/{short_code}/watch

Section titled “DELETE /api/items/{short_code}/watch”

Stop the watch of the caller on the item. No watch: nothing changes, and the answer is the same.

Parameter In Required Type Description
short_code path yes string The item
Response Body Meaning
200 WatchState The caller does not watch the item now
403 ErrorEnvelope The caller is a service account
404 ErrorEnvelope No item has the short code

GET /api/items/{short_code}/watchers

Section titled “GET /api/items/{short_code}/watchers”

Each person who watches the item, oldest watch first, with who added each watch. A person who watches a parent with its children is not in the list. Each member can read it.

Parameter In Required Type Description
short_code path yes string The item
Response Body Meaning
200 ItemWatchers The watchers of the item
404 ErrorEnvelope No item has the short code

PUT /api/items/{short_code}/watchers/{user}

Section titled “PUT /api/items/{short_code}/watchers/{user}”

Add a person of the organization as a watcher of the item. The person gets a watch notification that you added them, and then one for each coarse change of the item. A person who watches the item already: the watch does not change. me watches the item for you.

Parameter In Required Type Description
short_code path yes string The item
user path yes string The watcher: a user id, an email, a user name, or me

Request body (required): application/json, WatchRequest

Response Body Meaning
200 ItemWatchers The watchers of the item after the change
403 ErrorEnvelope The caller is a service account
404 ErrorEnvelope No item has the short code, the code is retired, or the item is archived
422 ErrorEnvelope The user is not a person of the organization

DELETE /api/items/{short_code}/watchers/{user}

Section titled “DELETE /api/items/{short_code}/watchers/{user}”

Remove a watcher of the item. Only the watcher or the person who added the watch can remove it. No watch: nothing changes.

Parameter In Required Type Description
short_code path yes string The item
user path yes string The watcher: a user id, an email, a user name, or me
Response Body Meaning
200 ItemWatchers The watchers of the item after the change
403 ErrorEnvelope The caller is not the watcher and did not add the watch
404 ErrorEnvelope No item has the short code
422 ErrorEnvelope No person has the user reference

GET /api/me/agent-keys

Section titled “GET /api/me/agent-keys”

The caller’s agent keys (metadata only, never a secret), newest first.

Response Body Meaning
200 ApiKeyListResponse Key metadata (never secrets)
403 ErrorEnvelope The caller is a service account

POST /api/me/agent-keys

Section titled “POST /api/me/agent-keys”

Make an agent key for the caller: return the secret ONCE, keep only its hash. Kairos refuses a service account, and a request made with an agent key.

Request body (required): application/json, CreateApiKeyRequest

Response Body Meaning
201 ApiKeyCreatedResponse Key made; the secret is shown once
403 ErrorEnvelope The caller is a service account, or the request uses an agent key
422 ErrorEnvelope Empty name, bad expiry, expires_at with no_expiry, or an unknown capability or board in the scope

DELETE /api/me/agent-keys/{key_id}

Section titled “DELETE /api/me/agent-keys/{key_id}”

Revoke one of the caller’s agent keys (soft: revoked_at set). The key of another person, or an unknown id → 404; already revoked → 409.

Parameter In Required Type Description
key_id path yes string Agent key id (UUID)
Response Body Meaning
200 DeletedResponse Key revoked
403 ErrorEnvelope The caller is a service account
404 ErrorEnvelope The caller has no key with this id
409 ErrorEnvelope Already revoked

POST /api/me/agent-keys/{key_id}/rotate

Section titled “POST /api/me/agent-keys/{key_id}/rotate”

Rotate one of the caller’s agent keys (KAIROS-T-0370). A new key with a new secret takes the place of the key. Kairos shows the secret once. The old secret works for the grace time (KAIROS_API_KEY_ROTATION_GRACE_SECS, 1 day by default), then it ends. A request made with an agent key cannot rotate a key. No body.

Parameter In Required Type Description
key_id path yes string Agent key id (UUID)
Response Body Meaning
201 ApiKeyRotatedResponse The new key; the secret is shown once
403 ErrorEnvelope The caller is a service account, or the request uses an agent key
404 ErrorEnvelope The caller has no key with this id
409 ErrorEnvelope The key is revoked, expired, or rotated already

GET /api/me/notification-settings

Section titled “GET /api/me/notification-settings”

The caller’s notification settings: each kind, and whether it is on.

Response Body Meaning
200 NotificationSettings Each kind, and whether it is on
403 ErrorEnvelope The caller is a service account

PUT /api/me/notification-settings

Section titled “PUT /api/me/notification-settings”

Turn kinds of notification on or off for the caller, and mute or unmute agent keys (KAIROS-T-0737). A kind that is not in the body does not change. Kairos refuses a body with no kind and no key.

Request body (required): application/json, UpdateNotificationSettingsRequest

Response Body Meaning
200 NotificationSettings The settings after the change
403 ErrorEnvelope The caller is a service account
404 ErrorEnvelope An id of mute_keys or unmute_keys is not an agent key
422 ErrorEnvelope The body names no kind and no key, or a key is in mute_keys and unmute_keys

GET /api/me/notifications

Section titled “GET /api/me/notifications”

The caller’s notifications: each unread one (newest first, 100 at most), then the 20 newest read ones. before gives the next page of unread ones. read_before gives the next page of read ones: 100 at most, read before that one (KAIROS-T-0584). The read state is the caller’s: the person, or the agent key of the request (KAIROS-T-0550). A service account has none.

Parameter In Required Type Description
before query no string The id of a notification. The page has the unread notifications older than it, and no read ones
read_before query no string The id of a read notification. The page has the read notifications that the caller read before it, 100 at most, and no unread ones
Response Body Meaning
200 NotificationList The unread notifications, then the newest read ones
404 ErrorEnvelope before or read_before is not a notification of the caller
422 ErrorEnvelope before and read_before together, or read_before is unread for the caller

POST /api/me/notifications/read

Section titled “POST /api/me/notifications/read”

Mark notifications of the caller read: ids, or all: true with up_to. The read is the caller’s: the person, or the agent key of the request (KAIROS-T-0550). An id that is not a notification of the caller is a 404 that names it, and nothing changes. An id that is read already does not change.

Request body (required): application/json, MarkNotificationsReadRequest

Response Body Meaning
200 MarkNotificationsReadResponse The ids that changed, and the unread count after
404 ErrorEnvelope An id is not a notification of the caller
422 ErrorEnvelope Neither ids nor all, or both, or all without up_to

GET /api/me/watches

Section titled “GET /api/me/watches”

Each watch of the caller, by code. An agent key gives the watches of its person.

Response Body Meaning
200 WatchList Each watch of the caller, by code
403 ErrorEnvelope The caller is a service account

GET /api/me/work

Section titled “GET /api/me/work”

The work of the caller, in two lanes.

  • Initiatives: the strategies and the initiatives that the caller owns.
  • Tasks: the claims of the caller and of the agent keys of the caller. The Todo, Active and Blocked tasks under an initiative of the caller. The tasks that one of these tasks blocks.

Each item has a state (todo, active, blocked) and its open blockers. The answer has no item in a done column.

Response Body Meaning
200 MyWork The two lanes of the work of the caller
401 ErrorEnvelope Missing/invalid token
403 ErrorEnvelope Not a member of the organization

POST /api/notices

Section titled “POST /api/notices”

Send a notice to a person (to) or to each member of a team (team). A notice is a text with an optional item link (KAIROS-T-0737). A notice from an agent key names the key and its person. Each key can send KAIROS_NOTICE_LIMIT_PER_HOUR notices in one hour (default 20); a notice to a team counts as one. A recipient who turned the kind notice off, or muted the key, gets nothing. A service account cannot send a notice.

Request body (required): application/json, SendNoticeRequest

Response Body Meaning
201 SendNoticeResponse The notice, and the persons who got it
403 ErrorEnvelope The caller is a service account, or the agent key has no member in its scope
404 ErrorEnvelope The team or the item is not found
422 ErrorEnvelope to and team both or neither, an unknown person, or an empty or long text
429 ErrorEnvelope NOTICE_RATE_LIMITED: the sender is at the limit of one hour

service-accounts

Section titled “service-accounts”

GET /api/org/agent-keys

Section titled “GET /api/org/agent-keys”

The agent keys of the persons of the organization, newest first (never a secret). Org-admin-only.

Parameter In Required Type Description
user query no string Only the keys of this person: a user id (UUID) or an email.
limit query no integer Page size (default 50, max 200).
offset query no integer Rows to skip (default 0).
Response Body Meaning
200 ListEnvelope_OrgAgentKey A page of the agent keys, with the owner of each
403 ErrorEnvelope The organization admin role is required
422 ErrorEnvelope The user filter names no person

DELETE /api/org/agent-keys/{key_id}

Section titled “DELETE /api/org/agent-keys/{key_id}”

Revoke the agent key of any person (soft: revoked_at set). Writes an activity row and tells the owner. Org-admin-only. An unknown id, or the id of a service-account key → 404; already revoked → 409.

Parameter In Required Type Description
key_id path yes string Agent key id (UUID)
Response Body Meaning
200 DeletedResponse Key revoked
403 ErrorEnvelope The organization admin role is required
404 ErrorEnvelope No agent key has this id
409 ErrorEnvelope Already revoked

GET /api/service-accounts

Section titled “GET /api/service-accounts”

List the org’s service accounts. Org-admin-only.

Response Body Meaning
200 ServiceAccountListResponse Service accounts
403 ErrorEnvelope Org admin required

POST /api/service-accounts

Section titled “POST /api/service-accounts”

Create a service account (a machine principal + its org membership). Org-admin-only.

Request body (required): application/json, CreateServiceAccountRequest

Response Body Meaning
201 ServiceAccountView Service account created
403 ErrorEnvelope Org admin required
422 ErrorEnvelope Empty name

DELETE /api/service-accounts/{id}

Section titled “DELETE /api/service-accounts/{id}”

Delete a service account and all its keys. Org-admin-only. Unknown id → 404.

Parameter In Required Type Description
id path yes string Service account id (UUID)
Response Body Meaning
200 DeletedResponse Deleted
403 ErrorEnvelope Org admin required
404 ErrorEnvelope Unknown service account

GET /api/service-accounts/{id}/keys

Section titled “GET /api/service-accounts/{id}/keys”

List a service account’s keys (metadata only). Org-admin-only.

Parameter In Required Type Description
id path yes string Service account id (UUID)
Response Body Meaning
200 ApiKeyListResponse Key metadata (never secrets)
403 ErrorEnvelope Org admin required
404 ErrorEnvelope Unknown service account

POST /api/service-accounts/{id}/keys

Section titled “POST /api/service-accounts/{id}/keys”

Mint an API key for a service account: return the secret ONCE, store only its hash. Org-admin-only. Unknown service account → 404.

Parameter In Required Type Description
id path yes string Service account id (UUID)

Request body (required): application/json, CreateApiKeyRequest

Response Body Meaning
201 ApiKeyCreatedResponse Key minted; secret shown once
403 ErrorEnvelope Org admin required
404 ErrorEnvelope Unknown service account
422 ErrorEnvelope Empty name, bad expiry, expires_at with no_expiry, or a scope (the key of a service account has none)

DELETE /api/service-accounts/{id}/keys/{key_id}

Section titled “DELETE /api/service-accounts/{id}/keys/{key_id}”

Revoke a key (soft: revoked_at set). Org-admin-only. Unknown ids → 404; already revoked → 409.

Parameter In Required Type Description
id path yes string Service account id (UUID)
key_id path yes string API key id (UUID)
Response Body Meaning
200 DeletedResponse Key revoked
403 ErrorEnvelope Org admin required
404 ErrorEnvelope Unknown service account or key
409 ErrorEnvelope Already revoked

POST /api/service-accounts/{id}/keys/{key_id}/rotate

Section titled “POST /api/service-accounts/{id}/keys/{key_id}/rotate”

Rotate a key of a service account (KAIROS-T-0370). A new key with a new secret takes the place of the key. Kairos shows the secret once. The old secret works for the grace time (KAIROS_API_KEY_ROTATION_GRACE_SECS, 1 day by default), then it ends. Org-admin-only. No body.

Parameter In Required Type Description
id path yes string Service account id (UUID)
key_id path yes string API key id (UUID)
Response Body Meaning
201 ApiKeyRotatedResponse The new key; the secret is shown once
403 ErrorEnvelope Org admin required
404 ErrorEnvelope Unknown service account or key
409 ErrorEnvelope The key is revoked, expired, or rotated already

scim-tokens

Section titled “scim-tokens”

GET /api/scim-tokens

Section titled “GET /api/scim-tokens”

List the tenant’s SCIM tokens (metadata only). Org-admin-only.

Response Body Meaning
200 ScimTokenListResponse Token metadata (never secrets)
403 ErrorEnvelope Org admin required

POST /api/scim-tokens

Section titled “POST /api/scim-tokens”

Create a SCIM token: mint the secret, store only its hash, return the secret ONCE. Org-admin-only.

Request body (required): application/json, CreateScimTokenRequest

Response Body Meaning
201 ScimTokenCreatedResponse Token created; secret shown once
403 ErrorEnvelope Org admin required
422 ErrorEnvelope Empty name

DELETE /api/scim-tokens/{id}

Section titled “DELETE /api/scim-tokens/{id}”

Revoke a SCIM token (soft: revoked_at set, row retained for audit). Unknown id → 404; already revoked → 409. Org-admin-only.

Parameter In Required Type Description
id path yes string SCIM token id (UUID)
Response Body Meaning
200 ScimTokenRevokedResponse Token revoked
403 ErrorEnvelope Org admin required
404 ErrorEnvelope Unknown token id
409 ErrorEnvelope Already revoked