Schemas

The wire shapes the operations reference, alphabetically. A field is optional unless marked required.

ActivityEntry

One activity_log row, as returned by GET /api/activity.

Field	Type	Required	Description
action	string	yes	`transition
actor_id	string	yes	Who did it (user UUID).
agent_key_id	string, nullable	no	The agent key (UUID) of the request that made this change, when an agent made it with the agent key of a person (KAIROS-T-0359). The actor is still the person: show “Alice (agent)”. Null for a change made without an agent key, and for each change made before Kairos recorded the key.
details	string	yes	Structured context, e.g. "column:Draft->Active".
entity_archived_at	string, nullable	no	When the item acted on was archived (RFC 3339). Null for a live item, and when entity_short_code is null.
entity_id	string, nullable	no	The item acted on (UUID). For a relationship between two items it is the source of the edge, and details names the two (KAIROS-T-0638; null in older rows whose source is not known). For an impacts link it is the document or the ADR of the link (COLLIERY-T-0269).
entity_repository	ActivityRepository, nullable	no
entity_short_code	string, nullable	no	The short code of the item acted on (COLLIERY-T-0262), live or archived. Null when the entry is not about an item (a board, a team, a member), and when Kairos has no item with the id.
entity_title	string, nullable	no	The title of the item acted on, as it is now. Null when entity_short_code is null.
entity_type	string, nullable	no	`strategy
id	string	yes	Row id (UUID).
occurred_at	string	yes	RFC 3339.

ActivityRepository

The repository that an activity entry is about. It has enough data to link the repository and the pull request or branch of a forge_event.

Field	Type	Required	Description
forge	string	yes	github, gitlab or other.
full_name	string	yes	owner/repo on GitHub, group/subgroup/project on GitLab.
slug	string	yes	Tenant-unique handle.
url	string	yes	The web URL of the repository on the forge.

AddBoardMemberRequest

Body of POST /api/boards/{id}/members.

Field	Type	Required	Description
capabilities	array of string	yes	Capabilities to grant (KAIROS-A-0006 vocabulary or glob; at least one).
user_id	string	yes	public.users.id (UUID).

The server refuses a body with a field that is not in this table (Errors).

AddOrgMemberRequest

Body of POST /api/members. The user is resolved by email from public.users — users are JIT-provisioned at first login, so an unknown email means the person must log in once first (404 with that guidance).

Field	Type	Required	Description
email	string	yes
role	string, nullable	no	`admin

The server refuses a body with a field that is not in this table (Errors).

AddStreamTeamRequest

Body of POST /api/delivery-streams/{id}/teams.

Field	Type	Required	Description
team_id	string	yes	Team id (UUID).

The server refuses a body with a field that is not in this table (Errors).

AddTeamMemberRequest

Body of POST /api/teams/{id}/members.

Field	Type	Required	Description
user_id	string	yes	public.users.id (UUID).

The server refuses a body with a field that is not in this table (Errors).

Adr

An Architecture Decision Record, as returned by /api/adrs. Board placement is optional (board_id/column_id both set or both null).

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live. Archiving hides work from default listings and nothing more (KAIROS-A-0020) — anything serving an archived row marks it, so an auditor never mistakes it for live work.
board_id	string, nullable	no	ADR board (UUID), if placed on one.
column_id	string, nullable	no	Current column (UUID), if placed on a board.
content	string	yes	Markdown content.
created_at	string	yes	RFC 3339.
created_by	string	yes	Creator user id (UUID).
decision_date	string, nullable	no	YYYY-MM-DD.
decision_maker	string, nullable	no
id	string	yes	Entity id (UUID).
impacts	array of Impact	no	The repositories that the ADR impacts (COLLIERY-T-0269), by slug. An impacts link says what the ADR is about. It gives no right.
notes	array, nullable	no	The notes of the item, in the order of their ids (KAIROS-T-0630). Present on the read of one item (GET /api/{family}/{short_code}), empty when the item has none. Absent from lists and from the answers of writes. A note is not part of content.
short_code	string	yes	Tenant-scoped short code ({PREFIX}-A-{NNNN}).
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string	yes	Last editor user id (UUID).
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).

AdrCard

An ADR on a board or in a search (KAIROS-T-0602).

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live (KAIROS-A-0020).
board_id	string, nullable	no	ADR board (UUID), if placed on one.
column_id	string, nullable	no	Current column (UUID), if placed on a board.
content	string, nullable	no	Markdown content. Only with fields=full on the board route. A card has no notes (KAIROS-T-0630): the read of the item gives them.
created_at	string	yes	RFC 3339.
created_by	string, nullable	no	Creator user id (UUID). Only with fields=full on the board route.
decision_date	string, nullable	no	YYYY-MM-DD.
decision_maker	string, nullable	no
entered_column_at	string, nullable	no	When the card entered its column, RFC 3339: its last move, or its creation (KAIROS-T-0649). Present on the board route; absent on a search hit.
id	string	yes	Entity id (UUID).
impacts	array of Impact	no	The repositories that the ADR impacts (COLLIERY-T-0269).
notes_count	integer, nullable	no	The number of the notes of the item (KAIROS-T-0649). Present on the board route; absent on a search hit.
short_code	string	yes	Tenant-scoped short code ({PREFIX}-A-{NNNN}).
snippet	string, nullable	no	About 200 characters of the content, near the first match of q. Only on a search hit.
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string, nullable	no	Last editor user id (UUID). Only with fields=full on the board route.
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).

AgentTriage

Who decides the triage of intake on a board (KAIROS-T-0428). Intake is a task in the support lane. Off (the default): an agent proposes with a note, and a person decides. On: an agent moves intake itself, and the activity log names the agent.

Field	Type	Required	Description
agents_decide	boolean	yes
board_id	string	yes

ApiKeyCreatedResponse

POST /api/service-accounts/{id}/keys response — the ONLY place the secret appears.

Field	Type	Required	Description
created_at	string	yes
expires_at	string, nullable	no
id	string	yes
key	string	yes	The full API key. Shown once; store it now.
name	string	yes
prefix	string	yes
scope	KeyScopeView, nullable	no

ApiKeyListResponse

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

Field	Type	Required	Description
items	array of ApiKeyView	yes
total	integer	yes

ApiKeyRotatedResponse

The response of a rotation (KAIROS-T-0370). It has the new key and its secret, and the end of the old secret. Kairos shows the secret once.

Field	Type	Required	Description
created_at	string	yes
expires_at	string, nullable	no
id	string	yes	The id of the new key.
key	string	yes	The new secret. Shown once; store it now.
name	string	yes
prefix	string	yes
replaced_key_expires_at	string	yes	The old secret works until this time (RFC 3339): the end of the grace time (KAIROS_API_KEY_ROTATION_GRACE_SECS).
replaced_key_id	string	yes	The id of the old key.

ApiKeyView

One row of GET /api/service-accounts/{id}/keys — never a secret or hash.

Field	Type	Required	Description
created_at	string	yes
expires_at	string, nullable	no
id	string	yes
last_used_at	string, nullable	no
name	string	yes
prefix	string	yes
replaced_by	string, nullable	no	The key that a rotation made in place of this key (KAIROS-T-0370). The old secret works until expires_at, the end of the grace time.
revoked_at	string, nullable	no
scope	KeyScopeView, nullable	no

AppendNoteRequest

Body of POST /api/{entity_type}/{short_code}/notes (KAIROS-T-0367): the text of a note. A note is a row of its own (KAIROS-T-0630).

Field	Type	Required	Description
text	string	yes	The markdown text of the note. It must not be empty.

The server refuses a body with a field that is not in this table (Errors).

AppendNoteResponse

Response of POST /api/{entity_type}/{short_code}/notes (KAIROS-T-0367): the id of the note (KAIROS-T-0504). A note writes no version of the content (KAIROS-T-0630).

Field	Type	Required	Description
note_id	string	no	The id of the note: n-3. The item page anchors it (#n-3). The default is for the client only: a response of an older server has no note_id.
short_code	string	yes	The item’s short code.
version	integer	yes	The version of the content of the item. A note does not change it.

ArchiveCompletedResponse

Response of POST /api/boards/{id}/archive-completed (KAIROS-T-0363): the tasks of the done columns that the call archived.

Field	Type	Required	Description
board_id	string	yes	The board (UUID).
count	integer	yes	How many tasks the call archived.
short_codes	array of string	yes	The short codes of the archived tasks, sorted.

ArchivedTeamPage

One archived node of a team (KAIROS-T-0439): GET /api/teams/{id}/archived-pages. Restore it with POST /api/teams/{id}/pages/{page_id}/restore.

BlocksCounts

Dependency counts behind a board card’s blocked-by/blocks badges (KAIROS-T-0091).

Field	Type	Required	Description
blocked_by	integer	yes	Open incoming blocks edges (things blocking this item): the blocker is live, and neither end is in a terminal column (COLLIERY-T-0214).
blocks	integer	yes	Open outgoing blocks edges (things this item blocks): the blocked item is live, and neither end is in a terminal column (COLLIERY-T-0214).

Board

A board (/api/boards list element).

Field	Type	Required	Description
blockers_gate	boolean, nullable	yes	The board policy blockers_gate of a delivery board (KAIROS-T-0565): when true, a task with an open blocker does not move into a claims column or a done column. The refusal is a 422 BLOCKED. When false, the move goes on with a Kairos-Warning. False by default. null on each other level.
board_level	string	yes	`strategy
code_prefix	string	yes	The short-code prefix of the board (COLLIERY-T-3099): an item on the board gets a code {code_prefix}-{type letter}-{number}. It is set when the board is created and never changes. The default is for the client only: a response of an older server has no prefix.
created_at	string	yes	RFC 3339.
id	string	yes	Board id (UUID).
name	string	yes
owner_gate	boolean, nullable	yes	The board policy owner_gate of an initiative board (KAIROS-T-0643): when true, an initiative moves into its Active column only with an owner, and the owner of an initiative in Active or Monitoring cannot release it (a hand-off can change it). A refused move or release is a 422 OWNER_REQUIRED. True by default. null on each other level.
parent_gate	boolean, nullable	yes	The board policy parent_gate of a delivery board (KAIROS-T-0641): when true, a task moves into a claims column (Active) only while its parent initiative is active (in Active or Monitoring, or a bucket). A move under an initiative that is not active is a 422 PARENT_NOT_ACTIVE. True by default. null on each other level.
slug	string	yes
team_id	string, nullable	no	Owning team (UUID). A delivery board has one (COLLIERY-T-0230). An ADR board can have one: the ADR board of the team (COLLIERY-T-3102). A strategy or initiative board has one too (KAIROS-T-0440): the one in the create, or its own team. The ADR board of the organization has none.
updated_at	string	yes	RFC 3339.

BoardColumn

A board column.

Field	Type	Required	Description
board_id	string	yes	Owning board (UUID).
claims	boolean	yes	A task that a person moves into this column gets a claim for the person (KAIROS-T-0359). The Active column of a delivery board has it. The default is for the client only: a response of an older server has no claims, and it reads as false.
created_at	string	yes	RFC 3339.
id	string	yes	Column id (UUID).
is_done	boolean	yes	Occupants count as completed for children-progress rollups (KAIROS-T-0080). The server sends it in each response, so the schema shows it as required (COLLIERY-T-0254). The default is for the client only: a response of an older server has no is_done, and it reads as false.
keeps_claims	boolean	yes	A task with a claim keeps it in this column, and a task with no claim gets none here (KAIROS-T-0529). The Blocked column of a delivery board has it. The default is for the client only: a response of an older server has no keeps_claims.
name	string	yes
position	integer	yes	Display ordering, 0-indexed.
removed_at	string, nullable	yes	When this column was REMOVED from its board (RFC 3339), null while it is part of the board (KAIROS-T-0161, KAIROS-T-0164). GET /api/boards/{id} omits removed columns entirely unless it is asked for them (?include_removed_columns=true), so this is null on every default read. It is a timestamp only for a caller that wants the column an ARCHIVED card was put away in — the audit fact the soft delete exists to preserve. Named removed_at, not archived_at: the entity DTOs’ archived_at is the KAIROS-A-0020 work-item state, and a column is not work. The server sends it in each response, null for a live column, so the schema shows it as required and nullable (COLLIERY-T-0256, the pattern of COLLIERY-T-0254). The default is for the client only: a response of an older server has no removed_at, and it reads as None.
updated_at	string	yes	RFC 3339.
wip_limit	integer, nullable	yes	The most live items that the column should hold (KAIROS-T-0371); null: no limit. Kairos does not refuse a move into a column over its limit, and the answer has the header Kairos-Warning. The server sends it in each response; the default is for the client only (an older server).

BoardColumnItems

One column’s items in the GET /api/boards/{id}/items view: every live workflow item of every entity type currently in this column.

Field	Type	Required	Description
adrs	array of AdrCard	yes
column	BoardColumn	yes
initiatives	array of InitiativeCard	yes
item_count	integer	yes	The live items in the column, on each page (KAIROS-T-0371): the count that the WIP limit is for. Not changed by the filters or the page. The default is for the client only (an older server).
over_wip_limit	boolean	yes	item_count is above column.wip_limit.
strategies	array of StrategyCard	yes	The cards of the column (KAIROS-T-0602): no content unless the query has fields=full.
tasks	array of TaskCard	yes

BoardDetail

Board detail: the board plus its full configuration (GET /api/boards/{id}).

BoardFlow

The flow metrics of a board for a range (KAIROS-T-0372), from the history of the moves (activity_log). An archived item counts until its archive (KAIROS-T-0571), and a cancelled task apart from the done items. The start of an item is its first entry into a start column. A start column has claims (Active). With no such column, the column named Active is the start. An item is done in an is_done column; its done time is its last entry into one.

Field	Type	Required	Description
ageing	array of FlowAgeingItem	yes	The work in progress: each item that is not done and has a start, oldest first.
board_id	string	yes	The board (UUID).
board_slug	string	yes
cancelled_count	integer	yes	The cancelled tasks of the range, by the time of the cancel.
cumulative_flow	CumulativeFlow	yes
cycle_time	FlowCycleTime	yes
done_columns	array of string	yes	The done columns, by name.
done_count	integer	yes	The done items of the range (not cancelled).
done_without_start	integer	yes	The done items of the range that never entered a start column (no cycle time).
from	string	yes	The first day of the range, YYYY-MM-DD.
start_columns	array of string	yes	The start columns, by name. Empty: the board has no start, and no cycle time.
throughput	array of FlowWeek	yes	One row for each week of the range (weeks start on Monday, UTC).
to	string	yes	The last day of the range, YYYY-MM-DD.

BoardGrantChange

The changes on one board (an element of [ChangeUserGrantsRequest::changes]).

Field	Type	Required	Description
board_id	string	yes	The board (UUID).
grant	array of string	no	The capabilities to grant. Each must apply at the level of the board, and the person must not have it.
revoke	array of string	no	The stored grants to revoke (a glob too). The person must have each.

The server refuses a body with a field that is not in this table (Errors).

BoardItemsResponse

Response of GET /api/boards/{id}/items: one page of the items on the board, grouped by column (columns in position order). The order of the items is: the position of the column, then the type, then the short code (COLLIERY-T-0261). The order of the types is: strategy, initiative, task, ADR. Each column is in each page, and a column can have no item on a page.

Field	Type	Required	Description
blocks_summary	object	yes	Blocked-by/blocks counts keyed by short code, for every item on this board with at least one open blocks edge (KAIROS-T-0091) — one grouped query; soft-deleted neighbors never count. An edge is open only while neither end sits in a terminal column (COLLIERY-T-0214): done work does not block and is not blocked, so a card in a terminal column has no entry. The server sends it in each response, so the schema shows it as required (COLLIERY-T-0254). It is an empty map when no item has an open blocks edge. The default is for the client only.
board	Board	yes
children_progress	object	yes	(done, total) direct-children counts keyed by the PARENT item’s short code, for every item on this board that has children (KAIROS-T-0080) — computed in one grouped query, never per item. The server sends it in each response, so the schema shows it as required (COLLIERY-T-0254). It is an empty map when no item has children. The default is for the client only.
columns	array of BoardColumnItems	yes
item_metadata	object, nullable	no	With with_metadata=true only (KAIROS-T-0368): the metadata values of each item of the page, keyed by short code and then by the slug of the definition. An item with no value has no entry. Absent when the query did not ask for it.
item_teams	object	yes	The teams of each strategy and initiative of the page, keyed by short code (KAIROS-T-0321), by slug — one query for the board. An item with no team has no entry. The server sends it in each response, so the schema shows it as required. It is an empty map when no item has a team. The default is for the client only.
limit	integer	yes	The limit that the server applied.
offset	integer	yes	The offset that the server applied.
total	integer	yes	The number of items on the board after the filters, on all pages (COLLIERY-T-0261). The default is for the client only: a response of an older server has no total, and it has each item.

BoardMember

A board member and their capability grants (GET /api/boards/{id}/members element).

Field	Type	Required	Description
capabilities	array of string	yes	The user’s capability grants on this board (sorted).
display_name	string	yes
email	string	yes
user_id	string	yes	public.users.id (UUID).
user_name	string	no	The user name: write @<user name> to mention the person (KAIROS-T-0665). An older server does not send it.

BoardTransition

An allowed column-to-column transition edge.

Field	Type	Required	Description
board_id	string	yes	Owning board (UUID).
from_column_id	string	yes	Source column (UUID).
id	string	yes	Transition id (UUID) — used by DELETE /api/boards/{id}/transitions/{transition_id}.
to_column_id	string	yes	Target column (UUID).

CancelTaskRequest

Body of POST /api/tasks/{short_code}/cancel (KAIROS-T-0362).

Field	Type	Required	Description
reason	string	yes	Why the task is cancelled. Must not be empty.

The server refuses a body with a field that is not in this table (Errors).

CascadePreviewResponse

Response of GET /api/{entity_type}/{short_code}/cascade-preview (KAIROS-T-0051) — the AUTHORITATIVE KAIROS-A-0001 descendant set a soft-delete of this item WOULD cascade to, computed WITHOUT deleting. The fields mirror [DeleteResponse] so a client can render the same warning before the delete as it shows after, and cascaded_short_codes is identical to the DeleteResponse a subsequent delete would return (barring concurrent edits).

Field	Type	Required	Description
cascade_count	integer	yes	How many live descendants a delete would cascade to (root excluded).
cascaded_short_codes	array of string	yes	Short codes of the live descendants a delete would cascade to, sorted.
not_reached	array of NotReached	no	The live descendants that an archive BY THIS CALLER would not reach, sorted by short code (COLLIERY-T-0234). The preview answers for the caller who asks: a different caller can get a different answer. Absent when the archive would reach each descendant.
short_code	string	yes	The item’s short code (the cascade root).

ChangeUserGrantsRequest

Body of PATCH /api/members/{user_id}/grants (KAIROS-T-0413): the changes to the grants of one person on one or more boards. Kairos applies all of them in one transaction, or none.

Field	Type	Required	Description
changes	array of BoardGrantChange	yes	One entry for each board (at least one; a board once only).

The server refuses a body with a field that is not in this table (Errors).

ChildColumnProgress

One column bucket of a children-progress rollup (KAIROS-T-0080).

Field	Type	Required	Description
board_id	string	yes	The column’s board (children may span boards).
cancelled	integer	yes	The cancelled tasks among count (KAIROS-T-0567).
column_id	string	yes	Column id (UUID).
column_name	string	yes
count	integer	yes
is_done	boolean	yes

ChildrenProgressResponse

Response of GET /api/{entity_type}/{short_code}/children-progress (KAIROS-T-0080): the item’s direct parent-edge children grouped by their board column. done counts children in is_done columns; when NO involved column is flagged, clients must show composition only, never a done percentage.

Field	Type	Required	Description
by_column	array of ChildColumnProgress	yes	Per-column composition of the children that count, board-then-position order.
cancelled	integer	yes	Cancelled tasks among the children (KAIROS-T-0567). A cancel is “won’t do”, not done. The default is for the client only: a response of an older server has no cancelled.
done	integer	yes	Children sitting in is_done columns, less the cancelled tasks (KAIROS-T-0567). An archived child in a done column counts here (KAIROS-T-0571).
has_done_columns	boolean	yes	False when no board hosting the children has a done-flagged column — show composition only, never a done fraction. The server sends it in each response, so the schema shows it as required (COLLIERY-T-0254). The default is for the client only: a response of an older server has no has_done_columns, and it reads as false.
open	integer	yes	Children that are not done and not cancelled: total - done - cancelled.
removed	integer	yes	Children archived from a column that is not done (KAIROS-T-0571). They are not open work, and they are not in total. The default is for the client only: a response of an older server has no removed.
short_code	string	yes	The parent item’s short code.
total	integer	yes	Direct children that count: the live children, and the archived children in a done column (KAIROS-T-0571). Supports/informs material never counts.

ClearedItemTeamResponse

Response of DELETE /api/{entity_type}/{short_code}/teams/{team} (KAIROS-T-0321).

Field	Type	Required	Description
short_code	string	yes	The short code of the item.
team	string	yes	The slug of the team that is not set on the item by hand now.

CodeIndex

One indexed commit of a repository.

Field	Type	Required	Description
commit	string	yes	The commit, 40 (or 64) lower-case hex characters.
created_at	string	yes	When the index was first written, RFC 3339.
ref	string, nullable	no	The branch, the pull request or the tag that the index is for, if the sender gave it.
refs	array of CodeIndexRef	no	Each ref that points at the commit now (KAIROS-T-0750): the default branch, a tag, a pull request (pull/12). Empty for an index that no ref points at, or a server before 0.20.
schema_version	integer, nullable	no	The schema version of the index file (KAIROS-T-0518). It is null when the stored structure gives no version.
source	string	yes	upload, or build (the server built it after a push).
structure_bytes	integer	yes	The size of the structure (the index with no summaries), in bytes.
summary_keys	integer	yes	The summaries that the structure uses.
updated_at	string	yes	When the index was last written, RFC 3339.
vector_model	string, nullable	no	The model of the vectors, as provider/model/dimension.

CodeIndexBreaker

The breaker of the code index builder of a repository (KAIROS-T-0399), as [Repository] carries it. The lease of a build job can run out: its server stopped, ran out of memory, or stalled. That trips the breaker, and the build does not run again. Then the builder starts no build of the repository: no update, no first build. A build that a person asks for (POST /api/repositories/{slug}/code-indexes/rebuild) resets it.

Field	Type	Required	Description
reason	string, nullable	no	Why: the error of the build job that tripped it.
tripped	boolean	yes	True: the breaker is tripped.
tripped_at	string, nullable	no	When the breaker tripped, RFC 3339.

CodeIndexBuild

One run of the code index builder (KAIROS-T-0331). The trigger says what started it: a push, a first build, a request, or an upload.

Field	Type	Required	Description
commit	string, nullable	no	The commit of the run, once the fetch gave it.
edges	integer, nullable	no
error	string, nullable	no	The text of the failure, for a failed run.
files	integer, nullable	no	The counts of the index that an ok run wrote.
finished_at	string, nullable	no	When the run ended, RFC 3339. None while it runs.
id	string	yes
model	string, nullable	no	The model that wrote the summaries, as provider/model (KAIROS-T-0341). None for a run that made none.
outcome	string	yes	running, ok or failed.
ref	string, nullable	no	The branch that the run indexed, if known.
requested_by	string, nullable	no	The user who asked for the run or sent the upload. None for the builder.
scip_warnings	array of CodeIndexScipWarning	no	Each language that had no SCIP index in the run, and why (KAIROS-T-0478): its edges are by name. Empty when each SCIP indexer of the run gave its index.
started_at	string	yes	When the run started, RFC 3339.
summaries_made	integer, nullable	no	The summaries that the run made with the model.
summaries_missing	integer, nullable	no	The summaries that the index of the run does not have (KAIROS-T-0495): the provider refused a call for the rate, or another call failed. The next build makes them.
summaries_reused	integer, nullable	no	The summaries that the run reused with no model call (KAIROS-T-0335): from the pool of the repository, or from the work file of a run that did not end.
symbols	integer, nullable	no
trigger	string	yes	push, first, request or upload.

CodeIndexBuildList

The answer to GET /api/repositories/{slug}/code-indexes/builds.

Field	Type	Required	Description
builder	string, nullable	no	Set when no code index builder runs for the deployment (KAIROS-T-0394): the server has the role api, and no server with the role worker ran the new-commits sweep lately. The text says what to do.
disk	CodeIndexDiskUse, nullable	no
items	array of CodeIndexBuild	yes	The runs, newest first.
limit	integer	yes	The limit that the answer used.
offset	integer	no	The runs before the page, newest first (KAIROS-T-0584).
total	integer	yes	The runs of the repository, with those not in items.

CodeIndexCacheUse

The dependency caches of one language and their disk use.

Field	Type	Required	Description
bytes	integer	yes
language	string	yes
repositories	integer	yes	The count of the repositories with a cache.

CodeIndexDiskUse

The disk use of the builder of this server: its tools and its dependency caches (KAIROS-T-0478).

Field	Type	Required	Description
caches	array of CodeIndexCacheUse	yes	The dependency caches of the repositories, by language.
caches_bytes	integer	yes	The total of the dependency caches, in bytes.
caches_cap_bytes	integer	yes	The cap of the dependency caches, in bytes (KAIROS_CODE_INDEX_DEPS_CAP_MB).
free_bytes	integer, nullable	no	The free space of the disk of KAIROS_CODE_INDEX_DIR, in bytes.
tools	array of CodeIndexToolUse	yes	Each tool folder of KAIROS_CODE_INDEX_DIR/tools/, and the other files there (the archives) as other.

CodeIndexRef

One ref that points at an indexed commit (KAIROS-T-0750).

Field	Type	Required	Description
kind	string	yes	branch, tag or pull.
name	string	yes	The short name: main, v1.0.0, pull/12, merge-requests/12.

CodeIndexScipWarning

A language of a run with no SCIP index (KAIROS-T-0478).

Field	Type	Required	Description
language	string	yes	rust, go, typescript or python.
reason	string	yes	What failed: a missing tool, a download, a checksum, an install or the indexer.

CodeIndexSettings

The answer to GET /api/org/code-index-settings.

Field	Type	Required	Description
concurrency	integer	yes	The requests that a hosted summarizer sends at a time, 1 to 32.
default_summaries	CodeIndexSummaries	no	Where the summaries of a repository that follows the organization are made: embedded or hosted (KAIROS-T-0358).
hosted_repositories	array of string	no	The repositories whose summaries the hosted provider makes now: set to hosted, or following the organization when the default is hosted (KAIROS-T-0415). By slug.
summary	SummaryProviderSettings	yes
updated_at	string, nullable	no
updated_by	string, nullable	no	None when the tenant has no settings row (the defaults).
updated_by_name	string, nullable	no	The display name of updated_by (KAIROS-T-0415).
vectors	VectorProviderSettings	yes
version	integer	no	The version of the settings: 0 for the defaults, then 1 more at each write (KAIROS-T-0415). Send it back with a write.

CodeIndexSummaries

Where the summaries of the code index of a repository are made (KAIROS-T-0340).

One of: embedded, hosted, organization

CodeIndexToolUse

One tool folder and its disk use.

Field	Type	Required	Description
bytes	integer	yes
language	string, nullable	no	The language that uses it: rust, go, typescript, python, typescript, python (Node.js), or none.
name	string	yes	The folder: go-1.27.2, node-24.22.0, rust-1.93.0, … or other.

CreateAdrRequest

Body of POST /api/adrs. board_id/column_id follow the DDL rule: both set (on-board) or both omitted (off-board; creation is then org-admin-only, KAIROS-A-0006 fallback).

Field	Type	Required	Description
board_id	string, nullable	no	ADR board — SLUG or UUID (KAIROS-T-0150); omit for an off-board ADR.
column_id	string, nullable	no	Column (UUID); defaults to the board’s first column when board_id is set.
content	string	no	Markdown content; defaults to empty.
decision_date	string, nullable	no	YYYY-MM-DD.
decision_maker	string, nullable	no
parent	string, nullable	no	The short code of the item that the ADR supports: a strategy, an initiative or a task (KAIROS-T-0591). The server writes the supports edge in the transaction of the create: a refused parent leaves no ADR. A retired code finds its item.
title	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateApiKeyRequest

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

Field	Type	Required	Description
expires_at	string, nullable	no	Optional RFC 3339 expiry. Omitted: the key expires after the default life of the deployment (KAIROS_API_KEY_TTL_DAYS, 90 days by default), or never when that setting is 0.
name	string	yes	Operator label for the key (“gha-main”, …).
no_expiry	boolean	no	true: the key never expires (KAIROS-T-0370). Do not send it with expires_at.
scope	KeyScopeRequest, nullable	no

The server refuses a body with a field that is not in this table (Errors).

CreateBoardRequest

Body of POST /api/boards: creates a board seeded with the system default columns/transitions for its level (KAIROS-A-0002).

Field	Type	Required	Description
board_level	string	yes	`strategy
code_prefix	string	yes	The short-code prefix of the board (COLLIERY-T-3099). Required. It must match ^[A-Z][A-Z0-9]{1,9}$, and no live board of the same level can have it: each pair (prefix, type) is unique, and the level gives the types of a board. It never changes. A bad prefix is a 422 VALIDATION with details.field = code_prefix. A prefix that a live board of the same level has is a 409 CONFLICT that names that board.
name	string	yes
slug	string	yes
team_id	string, nullable	no	Owning team (UUID). Required for a delivery board (COLLIERY-T-0230). Optional for an ADR board: the ADR board of the team, with the prefix of the team (COLLIERY-T-3102). Leave it out for a strategy or initiative board.

The server refuses a body with a field that is not in this table (Errors).

CreateColumnRequest

Body of POST /api/boards/{id}/columns.

Field	Type	Required	Description
name	string	yes
position	integer	yes	0-indexed position; must not collide with an existing column (422 DUPLICATE_COLUMN_POSITION).

The server refuses a body with a field that is not in this table (Errors).

CreateDispatchRuleRequest

POST /api/boards/{id}/dispatch-rules body.

Field	Type	Required	Description
column	string, nullable	no	The name or the id of a column of the board. Required for entered_column; for unblocked, the column the task must be in.
metadata_slug	string, nullable	no	Only tasks with this metadata: the slug of a definition. Send it with metadata_value. KAIROS-T-0696: the server also accepts the name definition, the name on MCP.
metadata_value	string, nullable	no	The value of metadata_slug that matches.
repository	string, nullable	no	Only tasks of this repository: its slug or its id.
target_id	string	yes	The id of a webhook target of the board.
task_type	string, nullable	no	Only tasks of this type: `task
trigger	string, nullable	no	entered_column (the default) or unblocked.

The server refuses a body with a field that is not in this table (Errors).

CreateDocumentRequest

Body of POST /api/documents. A document has an owner board from its create (COLLIERY-T-0269), and board is required (COLLIERY-T-3109). The document names that board as its owner, and its code gets the prefix of that board. The caller needs manage_documents on that board. With parent_short_code, the document also supports that item: a strategy, an initiative, or a task. The server creates the supports edge. The parent gives no authority over the document. The server refuses a body with no board, or with a null or empty board: 422 VALIDATION, and details.field is board.

Field	Type	Required	Description
board	string	yes	The owner board (slug or UUID), required: a live board of each level. The document is not a card of the board. An absent or null value reads as empty, so that the server gives the refusal that names board.
content	string, nullable	no	Markdown content. Omitted + template_id set = the template’s content is stamped in.
parent_short_code	string, nullable	no	Short code of the workflow item this document supports (optional).
template_id	string, nullable	no	Template to stamp content + metadata defaults from (UUID).
title	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateExternalRefRequest

Body of POST /api/{entity_type}/{short_code}/external.

Field	Type	Required	Description
label	string, nullable	no	The label, at most 200 characters. Empty is no label.
uri	string	yes	The URI. The scheme is http, https or mailto; each other scheme is refused.

The server refuses a body with a field that is not in this table (Errors).

CreateForgeConnectionRequest

Body of POST /api/forge-connections: connect webhooks for a registered repository (slug or UUID). Register the repository first via POST /api/repositories; its forge must be github or gitlab.

Field	Type	Required	Description
repository	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateImpactRequest

Body of POST /api/{entity_type}/{short_code}/impacts (COLLIERY-T-0269): the repository that the item impacts.

Field	Type	Required	Description
repository	string	yes	A live repository of the organization, by slug or UUID. It can be the repository of each team.

The server refuses a body with a field that is not in this table (Errors).

CreateInitiativeRequest

Body of POST /api/initiatives.

Field	Type	Required	Description
board_id	string	yes	Board to create the initiative on — SLUG or UUID (KAIROS-T-0150).
bucket_type	string, nullable	no	Marks the initiative as a bucket of this kind (`tech_debt
column_id	string, nullable	no	The entry column of the board (UUID), the default. An initiative starts in Discovery (KAIROS-T-0643): a different column is a 422 VALIDATION on column_id. A move takes it on.
complexity	string, nullable	no	T-shirt sizing (`xs
content	string	no	Markdown content; defaults to empty.
parent	string, nullable	no	The short code of the parent strategy (KAIROS-T-0572). The server writes the parent edge in the transaction of the create: a refused parent leaves no initiative. A retired code finds its item.
title	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateLocalAccountRequest

POST /api/local-accounts body.

Field	Type	Required	Description
display_name	string, nullable	no	Display name. Defaults to the email when absent.
email	string	yes	The person’s email. Lower-cased and trimmed; it is the login identifier.
password	string	yes	The initial password. At least [crate::local_auth::MIN_PASSWORD_LEN] characters.
role	string, nullable	no	Organization role, member (default) or admin.

The server refuses a body with a field that is not in this table (Errors).

CreateMetadataDefinitionRequest

Body of POST /api/metadata-definitions (org admin).

Field	Type	Required	Description
entity_types	array of string	no	Entity types the definition applies to (KAIROS-T-0078); empty = all types.
enum_options	array of string	no	Required non-empty for enum; forbidden otherwise.
field_type	string	yes	`string
name	string	yes
slug	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateRelationshipRequest

Body of POST /api/relationships. The caller may edit the item at either end (the link rule, COLLIERY-T-0228).

Field	Type	Required	Description
relationship	string	yes	`parent
source_short_code	string	yes	Short code of the edge’s source item (KAIROS-A-0001 orientation).
target_short_code	string	yes	Short code of the edge’s target item.

The server refuses a body with a field that is not in this table (Errors).

CreateRepositoryRequest

Body of POST /api/repositories.

Field	Type	Required	Description
default_branch	string, nullable	no	A branch name that git accepts, 255 characters at most. With a value, the branch is set by hand, and the code index builder indexes it. With no value, the builder follows the default branch of the forge, read at each fetch; until the first fetch the value is main (KAIROS-T-0430).
description	string, nullable	no	Short “how to work here” blurb for agents.
forge	string	yes	`github
repo_full_name	string	yes	The name on the forge — must match what the forge sends in webhook payloads. github: 2 parts (owner/repo). gitlab: 2 or more parts (group/subgroup/project). other: 1 or more parts. No space, no .git at the end, 255 characters at most.
repo_url	string	yes	Browser URL of the repository: an absolute http or https URL with a host, no space, and no user name or password (each member can read it). 2048 characters at most.
slug	string, nullable	no	Tenant-unique slug; defaults to one derived from repo_full_name (acme/payments-api → acme-payments-api).
team	string	yes	The owning team (UUID or slug). Exactly one (KAIROS-A-0019).

The server refuses a body with a field that is not in this table (Errors).

CreateScimTokenRequest

POST /api/scim-tokens body.

Field	Type	Required	Description
name	string	yes	Operator label (“okta-prod”, …).

The server refuses a body with a field that is not in this table (Errors).

CreateServiceAccountRequest

POST /api/service-accounts body.

Field	Type	Required	Description
name	string	yes	Operator label (“ci-deploy”, …).

The server refuses a body with a field that is not in this table (Errors).

CreateStandupGroupRequest

POST /api/standup-groups body.

Field	Type	Required	Description
name	string	yes	1 to 100 characters. Unique in the organization, with no regard to case.
people	array of string	no	The people of the group: the user id (UUID) or the user name of each. Each must be a person of the organization. Default: none.

The server refuses a body with a field that is not in this table (Errors).

CreateStrategyRequest

Body of POST /api/strategies.

Field	Type	Required	Description
board_id	string	yes	Board to create the strategy on — SLUG or UUID (KAIROS-T-0150).
column_id	string, nullable	no	Column to place it in (UUID); defaults to the board’s first column.
content	string	no	Markdown content; defaults to empty.
hypothesis	string, nullable	no
title	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateStreamRequest

Body of POST /api/delivery-streams.

Field	Type	Required	Description
description	string, nullable	no
name	string	yes
slug	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateStructureGrantRequest

Body of POST /api/structure-grants.

Field	Type	Required	Description
board	string, nullable	no	The board (slug or UUID) of a board grant. Omit it for a grant at the organization.
user	string	yes	The principal: a user id (UUID), an email, or a user name of a member of the organization. A service account is given by its id.

The server refuses a body with a field that is not in this table (Errors).

CreateTaskRequest

Body of POST /api/tasks.

Field	Type	Required	Description
board_id	string, nullable	no	Board to create the task on — SLUG or UUID (KAIROS-T-0150). Optional when team_id is given: the task then goes to the delivery board of that team. A request with no board and no team is a 422, with or without a repository (COLLIERY-T-0217, COLLIERY-A-0023). Until then a repository alone chose the board (KAIROS-T-0104).
column_id	string, nullable	no	The entry column of the board (UUID), the default (KAIROS-T-0566). A task starts there, for every caller: any other column is a 422 that names the entry column. Create the task, then move it.
content	string	no	Markdown content; defaults to empty.
from_team	string, nullable	no	The team that sends the task, by slug or UUID (KAIROS-T-0426). When it is not the team of the board, the task is a request whoever sends it: entry column, support lane. Omit it for today’s rule. Kairos does not keep it on the task: name the sending team in the body.
parent	string, nullable	no	The short code of the parent initiative (KAIROS-T-0572). The server writes the parent edge in the transaction of the create: a refused parent leaves no task. A retired code finds its item. In a claims column, parent_gate applies (KAIROS-A-0040).
repository	string, nullable	no	The repository the task links to (slug or UUID, KAIROS-T-0104). An optional link that says where the code is. It can be any live repository, of any team, and it does not choose the board (COLLIERY-T-0217, COLLIERY-A-0023). repository is THE reference field name on the wire (KAIROS-T-0115). The old name repository_id is refused, as each field that the route does not know (COLLIERY-T-0259).
task_type	string, nullable	no	`task
team_id	string, nullable	no	A team (UUID). It names the team whose delivery board gets the task, when no board is named (COLLIERY-T-0217); a team without exactly one live delivery board is a 422. With a board it must be that board’s team (COLLIERY-T-0216): any other team is a 422, never silently ignored. The BOARD decides the team of the task in both cases.
title	string	yes
work_class	string, nullable	no	Planned/Support lane (`planned

The server refuses a body with a field that is not in this table (Errors).

CreateTeamAnnouncementRequest

Body of POST /api/teams/{id}/announcements.

Field	Type	Required	Description
body	string	yes	Markdown body.
pinned	boolean	no	Pin it to the top of the feed.

The server refuses a body with a field that is not in this table (Errors).

CreateTeamPageRequest

Body of POST /api/teams/{id}/pages.

Field	Type	Required	Description
content	string	no	Markdown content (pages only); defaults to empty.
kind	string	yes	`folder
parent_id	string, nullable	no	Parent FOLDER (UUID); omit for a root node.
position	integer	no	Display order among siblings; defaults to 0.
slug	string	yes	URL segment, unique among siblings.
title	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateTeamRequest

Body of POST /api/teams. Creating a team also creates its delivery board (slug {slug}-delivery) from the system defaults, in the same transaction.

Field	Type	Required	Description
code_prefix	string	yes	The short-code prefix of the delivery board of the team (COLLIERY-T-3099). Required. The rules are those of code_prefix in POST /api/boards.
name	string	yes
slug	string	yes
team_type	string, nullable	no	`stream_aligned

The server refuses a body with a field that is not in this table (Errors).

CreateTemplateRequest

Body of POST /api/templates (org admin).

Field	Type	Required	Description
content	string	no	Starter markdown content; defaults to empty.
metadata	array of TemplateMetadataEntry	no	Metadata fields the template carries.
name	string	yes
sections	array of TemplateSection	no	The typed sections of the template (KAIROS-T-0729). Default: none. Not sent when empty, so that a server from before the field takes the body.
slug	string	yes

The server refuses a body with a field that is not in this table (Errors).

CreateTenantRequest

Body of POST /api/admin/tenants (deployment-admin only; see KAIROS_DEPLOYMENT_ADMINS).

Field	Type	Required	Description
initial_admin_external_id	string, nullable	no	OIDC sub of the user to seed as the tenant’s first org admin; defaults to the caller. The user must have authenticated once already (422 otherwise).
name	string	yes	Organization display name.
slug	string	yes	Organization slug (^[a-z][a-z0-9_-]{1,62}$).

The server refuses a body with a field that is not in this table (Errors).

CreateTransitionRequest

Body of POST /api/boards/{id}/transitions.

Field	Type	Required	Description
from_column_id	string	yes	Source column (UUID).
to_column_id	string	yes	Target column (UUID).

The server refuses a body with a field that is not in this table (Errors).

CreateWebhookTargetRequest

POST /api/boards/{id}/webhook-targets body.

Field	Type	Required	Description
name	string	yes	A name for people, for example Agent runner.
url	string	yes	An http:// or https:// URL. A loopback, private, link-local or shared address is refused unless the deployment sets KAIROS_WEBHOOK_ALLOW_PRIVATE.

The server refuses a body with a field that is not in this table (Errors).

CreatedForgeConnection

Response of connection creation and rotation: the connection plus the delivery URL and secret to paste into the forge. The secret is shown here and nowhere else — it is derived, never stored, so it cannot be re-read later (rotate to get a new one).

CreatedWebhookTarget

POST /api/boards/{id}/webhook-targets response: the target, and its secret. Kairos shows the secret this one time.

Field	Type	Required	Description
secret	string	yes	The key of the HMAC-SHA256 of X-Kairos-Signature. Keep it in the receiver. Kairos does not show it again.
target	WebhookTarget	yes

CumulativeFlow

The number of live items in each column at the end of each day of the range (UTC).

Field	Type	Required	Description
columns	array of string	yes	The columns: those of the board in position order, then an old name of a column that the history has (a column that has a new name now), in name order. An old name is in the list only when it has an item on a day of the range (KAIROS-T-0627).
days	array of CumulativeFlowDay	yes	One row for each day; counts has the order of columns.

CumulativeFlowDay

One day of the cumulative flow.

Field	Type	Required	Description
counts	array of integer	yes
date	string	yes	YYYY-MM-DD.

DefaultBranchSource

Where the default branch of a repository comes from (KAIROS-T-0430).

One of: forge, hand

DeleteResponse

Response of DELETE /api/{family}/{short_code} — the soft delete and its KAIROS-A-0001 cascade.

Field	Type	Required	Description
cascade_count	integer	yes	How many live descendants were cascaded to (root excluded).
cascaded_short_codes	array of string	yes	Short codes of the cascaded descendants, sorted.
not_reached	array of NotReached	no	The live descendants that the archive did not reach, sorted by short code (COLLIERY-T-0234). They stay live and keep their parent edge. Absent when the archive reached each descendant.
short_code	string	yes	The deleted item’s short code.

DeletedExternalRefResponse

Response of DELETE /api/{entity_type}/{short_code}/external/{id}.

Field	Type	Required	Description
short_code	string	yes	The short code of the item.
uri	string	yes	The URI of the reference that was removed.

DeletedImpactResponse

Response of DELETE /api/{entity_type}/{short_code}/impacts/{repository}.

Field	Type	Required	Description
repository	string	yes	The slug of the repository that the item does not impact now.
short_code	string	yes	The short code of the item.

DeletedResponse

DELETE response for both service accounts and keys.

Field	Type	Required	Description
deleted	boolean	yes
id	string	yes

DeliveryStream

A delivery stream (/api/delivery-streams).

Field	Type	Required	Description
created_at	string	yes	RFC 3339.
description	string, nullable	no
id	string	yes	Stream id (UUID).
name	string	yes
slug	string	yes
updated_at	string	yes	RFC 3339.

DictionaryProblem

One bad row of the dictionary.

Field	Type	Required	Description
line	integer	yes	The 1-based line of the row in the document.
message	string	yes

DictionaryTerm

One term of [OrganizationDictionary].

Field	Type	Required	Description
meaning	string	yes
part_of_speech	string	yes
word	string	yes	The term: one word or more, as the dictionary writes it.

DispatchRule

A dispatch rule of a board. With the trigger entered_column, the rule fires when a task that matches the filter enters column. With unblocked (KAIROS-T-0427), it fires when the last open blocker of a task that matches closes. Then the task must be in column, if the rule names one. Kairos sends one signed delivery to the target.

Field	Type	Required	Description
board_id	string	yes
column	string, nullable	no	The name of the column.
column_id	string, nullable	no	null: an unblocked rule with no column.
created_at	string	yes
created_by	string	yes
id	string	yes
metadata_slug	string, nullable	no	The slug of a metadata definition; null: no metadata filter.
metadata_value	string, nullable	no	The value of the metadata that matches (no case, no space at the ends).
repository	string, nullable	no	The slug of the repository; null: each repository, and none.
target	string	yes	The name of the target.
target_id	string	yes
task_type	string, nullable	no	`task
trigger	string	yes	entered_column or unblocked.

Document

A supporting document, as returned by /api/documents. Documents do not live on boards: a document is never a card, and it has no column. A document has an owner (COLLIERY-T-0269): the board that the document names (board_id). Each document has one (COLLIERY-T-3109). The lifecycle is an editorial label (KAIROS-T-0078), and never a board position.

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live. Archiving hides work from default listings and nothing more (KAIROS-A-0020) — anything serving an archived row marks it, so an auditor never mistakes it for live work.
board_id	string	yes	The owner board (UUID): the board that the document names (COLLIERY-T-0269). It gives the right to edit the document, and the prefix of its code. Each document has one (COLLIERY-T-3109).
content	string	yes	Markdown content.
created_at	string	yes	RFC 3339.
created_by	string	yes	Creator user id (UUID).
id	string	yes	Entity id (UUID).
impacts	array of Impact	no	The repositories that the document impacts (COLLIERY-T-0269), by slug. An impacts link says what the document is about. It gives no right.
lifecycle	string	yes	Editorial lifecycle: `draft
notes	array, nullable	no	The notes of the item, in the order of their ids (KAIROS-T-0630). Present on the read of one item (GET /api/{family}/{short_code}), empty when the item has none. Absent from lists and from the answers of writes. A note is not part of content.
section_check	SectionCheck, nullable	no
short_code	string	yes	Tenant-scoped short code ({PREFIX}-D-{NNNN}).
template_id	string, nullable	no	Template the document was stamped from (UUID), if any.
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string	yes	Last editor user id (UUID).
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).

DocumentCard

A document in a search (KAIROS-T-0602). A document is on no board column, so only search gives document cards.

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live (KAIROS-A-0020).
board_id	string	yes	The owner board (UUID).
created_at	string	yes	RFC 3339.
id	string	yes	Entity id (UUID).
impacts	array of Impact	no	The repositories that the document impacts (COLLIERY-T-0269).
lifecycle	string	yes	Editorial lifecycle: `draft
short_code	string	yes	Tenant-scoped short code ({PREFIX}-D-{NNNN}).
snippet	string, nullable	no	About 200 characters of the content, near the first match of q.
template_id	string, nullable	no	Template the document was stamped from (UUID), if any.
title	string	yes
updated_at	string	yes	RFC 3339.
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).

EdgeProposalDto

A proposed graph edge awaiting a human (KAIROS-A-0021 rule 6, KAIROS-T-0192).

Field	Type	Required	Description
claim	string	yes	What was claimed.
created_at	string	yes	When it was proposed, RFC 3339. A string like every other timestamp in these DTOs: this crate compiles to wasm and does not carry chrono.
id	string	yes	The proposal’s id.
relationship	string	yes	parent or blocks.
source	string	yes	The proposed edge’s source, by short code.
state	string	yes	pending, confirmed or rejected.
target	string	yes	The proposed edge’s target, by short code.
why	string	yes	Why, verbatim — what the proposer saw, not a summary of it.

ErrorBody

The error object of [ErrorEnvelope].

Field	Type	Required	Description
code	string	yes	Stable machine-readable code (CONFLICT, INVALID_TRANSITION, FORBIDDEN, NOT_FOUND, VALIDATION, …).
details	object	yes	Structured extras (e.g. current on 409, allowed_targets on 422 INVALID_TRANSITION, required_capability on 403); {} when there is nothing structured to add.
message	string	yes	Human-readable message.

ErrorEnvelope

The S-0005 error envelope: {"error": {"code", "message", "details"}}.

Field	Type	Required	Description
error	ErrorBody	yes

ExternalRef

One external reference of an item: a URI with a label. The API and the tools show it as the relationship external. A URI is not an item, so the reference is not an edge between two items.

Field	Type	Required	Description
created_at	string	yes	When the reference was made, RFC 3339.
created_by	string	yes	Who made the reference (user id, UUID).
id	string	yes	The id of the reference (UUID). DELETE .../external/{id} names it.
label	string, nullable	no	The label, when the reference has one.
relationship	string	yes	Always external.
uri	string	yes	The URI, with the scheme http, https or mailto.

FlowAgeingItem

One item in progress, and its age.

Field	Type	Required	Description
age_days	number	yes	The time from the start to now, in days.
column	string	yes	The column of the item now.
short_code	string	yes
started_at	string	yes	The start of the item (RFC 3339).
title	string	yes

FlowCycleTime

The cycle time of the done items of the range (KAIROS-T-0372): from the start to the done time, in days.

Field	Type	Required	Description
count	integer	yes	The number of items with a cycle time.
items	array of FlowCycleTimeItem	yes	Each item, in the order of its done time.
mean_days	number, nullable	no
median_days	number, nullable	no
p85_days	number, nullable	no	The 85th percentile (nearest rank).

FlowCycleTimeItem

One done item and its cycle time.

Field	Type	Required	Description
days	number	yes
done_at	string	yes	RFC 3339.
short_code	string	yes
started_at	string	yes	RFC 3339.
title	string	yes

FlowWeek

The throughput of one week.

Field	Type	Required	Description
cancelled	integer	yes	The tasks cancelled in the week.
done	integer	yes	The items that went to a done column in the week (not cancelled).
week_start	string	yes	The Monday of the week, YYYY-MM-DD.

ForgeConnection

The webhook wiring of one repository (KAIROS-T-0106 re-key: repo identity and ownership live on the embedded repository). The webhook secret is never carried here — it is returned exactly once, by [CreatedForgeConnection].

Field	Type	Required	Description
created_at	string	yes	RFC 3339.
forge	string	yes	`github
id	string	yes	Connection id (UUID) — also the webhook URL’s last segment.
repository	RepositoryRef	yes	The repository this connection delivers for.

ForgeFilterRule

The two patterns of one field of the forge filter (KAIROS-T-0479). A pattern is a Rust regular expression of 512 bytes or fewer. It can match any part of the value: use ^ and $ to match all of it. Kairos admits an event when the value matches include and does not match exclude.

Field	Type	Required	Description
exclude	string, nullable	no	Default empty: exclude nothing.
include	string, nullable	no	Default .* (everything). An empty pattern is the same as .*.

The server refuses a body with a field that is not in this table (Errors).

ForgeFilters

The forge filters of a repository, one rule per field (KAIROS-T-0479). Kairos reads branch_name for a branch; pr_head_branch, pr_title and pr_author for a pull request; issue_title and issue_author for an issue.

Field	Type	Required	Description
branch_name	ForgeFilterRule, nullable	no
issue_author	ForgeFilterRule, nullable	no
issue_title	ForgeFilterRule, nullable	no
pr_author	ForgeFilterRule, nullable	no
pr_head_branch	ForgeFilterRule, nullable	no
pr_title	ForgeFilterRule, nullable	no

The server refuses a body with a field that is not in this table (Errors).

ForgeRef

One branch or pull request of a repository, as the forge reported it (KAIROS-T-0480). Kairos records each one that the forge filter of the repository admits, with or without a short code.

Field	Type	Required	Description
author	string	yes	The forge login of the author.
external_id	string	yes	PR/MR number, or the branch name.
forge	string	yes	`github
forge_updated_at	string	yes	RFC 3339.
head_branch	string	yes	The head branch of a pull request, or the branch itself.
item_short_codes	array of string	yes	The short codes of the live items that link to it.
kind	string	yes	`branch
linked	boolean	yes	False when no item links to it: its branch name, title and body have no live short code.
repo_full_name	string	yes	owner/repo.
repository	string	yes	The slug of the repository in Kairos.
state	string	yes	`open
title	string	yes
url	string	yes	Browser URL on the forge.

GraphEdge

One typed directed edge between two returned nodes.

Field	Type	Required	Description
depth	integer	yes	Minimum view depth at which BOTH endpoints are visible.
relationship	string	yes	`parent
source_id	string	yes	Source entity id (UUID).
target_id	string	yes	Target entity id (UUID).

GraphNode

One hydrated node of the focal subgraph.

Field	Type	Required	Description
archived_at	string, nullable	no	When this node was archived, RFC 3339; absent while it is live. The subgraph is archived-INCLUSIVE (KAIROS-T-0158) — omitting a node used to break the paths THROUGH it, leaving the far side floating with no route back to the focus. Clients must draw a marked node distinctly; drawing it as live is the one wrong answer.
degree	integer	yes	The node’s TOTAL edge count — clients render +N where N = degree - edges shown for undisplayed neighbors. Archived neighbours count, because they are drawn.
depth	integer	yes	Minimum hop distance from the focus (0 = the focus itself).
done	boolean	yes	true while this node is in a terminal column, a column with is_done (COLLIERY-T-0233). Done work does not block, and nothing blocks done work: a blocks edge with a done node at one end is history. Clients must draw that edge differently from an open blocker. false for a node with no column. The server sends it in each response, so the schema shows it as required (COLLIERY-T-0247). The default is for the client only: a response of an older server has no done, and it reads as false.
entity_type	string	yes	`strategy
id	string	yes	Entity id (UUID).
short_code	string	yes
status	string	yes	Board column name for workflow items; editorial lifecycle for documents (the A-0018 two-vocabulary split); off-board for ADRs without a board position.
title	string	yes

GraphResponse

Response of GET /api/{family}/{code}/graph.

Field	Type	Required	Description
depth	integer	yes	Effective depth bound the walk used (default 2, capped at the server’s MAX_TRAVERSE_DEPTH).
edges	array of GraphEdge	yes	ALL edges among the returned nodes — cross-links included, not just the discovery tree.
focus	string	yes	The focal item’s short code.
nodes	array of GraphNode	yes	Every node within depth hops (any relationship type, either direction), focus included at depth 0; ordered by short code. Archived nodes are present and marked (archived_at), never dropped.

HandOffRequest

Body of POST /api/tasks/{short_code}/hand-off (KAIROS-T-0359): the person who gets the claim, by user id, email or user name.

Field	Type	Required	Description
to	string	yes

The server refuses a body with a field that is not in this table (Errors).

HandOffTarget

A person who can get the claim of a task (KAIROS-T-0530). The person holds transition_items on the board of the task. GET /api/tasks/{short_code}/hand-off-targets gives a list of them.

Field	Type	Required	Description
display_name	string	yes
email	string	yes
user_id	string	yes	public.users.id (UUID).

HistoryVersion

One row of GET /api/{entity_type}/{short_code}/history.

Field	Type	Required	Description
agent_key_id	string, nullable	no	The agent key (UUID) of the request that made this change, when an agent made it with the agent key of a person (KAIROS-T-0359). The actor is still the person: show “Alice (agent)”. Null for a change made without an agent key, and for each change made before Kairos recorded the key.
edited_at	string	yes	RFC 3339.
edited_by	string	yes	Editor user id (UUID).
edited_by_name	string, nullable	no	The display name of the editor (KAIROS-T-0557). Null for an editor that Kairos does not know.
version	integer	yes	The content version this snapshot captured.

Impact

One impacts link of a document or of an ADR (COLLIERY-T-0269): a repository that the item is about. The link gives no right on the item and no right on the repository.

Field	Type	Required	Description
created_at	string	yes	When the link was made, RFC 3339.
relationship	string	yes	Always impacts.
repository	ImpactedRepository	yes	The repository.
target_kind	string	yes	Always repository. A later version can have other target kinds.

ImpactedRepository

The repository of an [Impact].

Field	Type	Required	Description
archived_at	string, nullable	no	When the repository was archived, RFC 3339. Absent while the repository is live. The link stays when the repository is archived.
forge	string	yes	`github
id	string	yes	Repository id (UUID).
repo_full_name	string	yes	owner/repo on GitHub, group/subgroup/project on GitLab.
slug	string	yes	The slug of the repository.

ImpactingItem

One document or ADR that impacts a repository (COLLIERY-T-0269), in [RepositoryDetail].

Field	Type	Required	Description
archived_at	string, nullable	no	When the item was archived, RFC 3339. Absent while the item is live.
column	string, nullable	no	The name of the column of an ADR. Null for a document, and for an ADR that is not on a board.
document_type	string, nullable	no	The value of the metadata document_type (vision, architecture, …). Null for an ADR, and for a document that has no document type.
entity_type	string	yes	document or adr.
lifecycle	string, nullable	no	The editorial lifecycle of a document: `draft
short_code	string	yes	The short code of the item.
title	string	yes

IndexFile

An index file in the OpenAPI document: the bytes of a kairos-index SQLite file.

Initiative

An initiative (Flight Level 2), as returned by /api/initiatives.

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live. Archiving hides work from default listings and nothing more (KAIROS-A-0020) — anything serving an archived row marks it, so an auditor never mistakes it for live work.
board_id	string	yes	Board the initiative sits on (UUID).
bucket_type	string, nullable	no	Bucket kind (`tech_debt
column_id	string	yes	Current column (UUID).
complexity	string, nullable	no	T-shirt sizing (`xs
content	string	yes	Markdown content.
created_at	string	yes	RFC 3339.
created_by	string	yes	Creator user id (UUID).
id	string	yes	Entity id (UUID).
is_bucket	boolean	yes	Whether this initiative is a bucket.
notes	array, nullable	no	The notes of the item, in the order of their ids (KAIROS-T-0630). Present on the read of one item (GET /api/{family}/{short_code}), empty when the item has none. Absent from lists and from the answers of writes. A note is not part of content.
owner	ItemOwner, nullable	no
short_code	string	yes	Tenant-scoped short code ({PREFIX}-I-{NNNN}).
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string	yes	Last editor user id (UUID).
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).

InitiativeCard

An initiative on a board or in a search (KAIROS-T-0602).

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live (KAIROS-A-0020).
board_id	string	yes	Board the initiative sits on (UUID).
bucket_type	string, nullable	no	Bucket kind (`tech_debt
cancellation	TaskCancellation, nullable	no
column_id	string	yes	Current column (UUID).
complexity	string, nullable	no	T-shirt sizing (`xs
content	string, nullable	no	Markdown content. Only with fields=full on the board route. A card has no notes (KAIROS-T-0630): the read of the item gives them.
created_at	string	yes	RFC 3339.
created_by	string, nullable	no	Creator user id (UUID). Only with fields=full on the board route.
entered_column_at	string, nullable	no	When the card entered its column, RFC 3339: its last move, or its creation (KAIROS-T-0649). Present on the board route; absent on a search hit.
id	string	yes	Entity id (UUID).
is_bucket	boolean	yes	Whether this initiative is a bucket.
notes_count	integer, nullable	no	The number of the notes of the item (KAIROS-T-0649). Present on the board route; absent on a search hit.
owner	ItemOwner, nullable	no
short_code	string	yes	Tenant-scoped short code ({PREFIX}-I-{NNNN}).
snippet	string, nullable	no	About 200 characters of the content, near the first match of q. Only on a search hit.
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string, nullable	no	Last editor user id (UUID). Only with fields=full on the board route.
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).

IssueImport

An import of the open issues of a repository (KAIROS-T-0487). It is a job of the job queue. POST and GET /api/repositories/{slug}/import-issues give it.

Field	Type	Required	Description
created_at	string	yes	When the import was asked for (RFC 3339).
error	string, nullable	no	Why the job failed, or why its last try stopped.
finished_at	string, nullable	no	When the job ended (RFC 3339); None while it waits or runs.
interval	string	no	The interval of the cadence of the repository (KAIROS-T-0670): off, or 15m, 1h, 1d.
job	string	yes	The id of the job (UUID).
pages	integer	yes	The pages of issues that the job took.
repository	string	yes	The slug of the repository.
result	IssueImportResult	yes	The counts so far; final when the job is done.
state	string	yes	queued, running, waiting (for the rate limit of the forge), done or failed.
sync	IssueSync	no	The sync state of the repository (KAIROS-T-0670).
waiting_until	string, nullable	no	While the job waits for the rate limit of the forge: the time it goes on (RFC 3339).

IssueImportResult

The counts of an import of the open issues (KAIROS-T-0483). The job writes them while it runs, and they stay after it ends (KAIROS-T-0487).

Field	Type	Required	Description
filtered	integer	yes	Issues that the forge filter does not admit.
imported	integer	yes	Issues that became a task.
items	array of string	yes	The short codes of the new tasks.
message	string	yes	A sentence for a person.
not_taken	integer	yes	Issues that no task could be made for; message says why.
skipped	integer	yes	Issues that were taken before (by a webhook or an earlier import).

IssueSync

The sync state of the issue import of a repository (KAIROS-T-0670). Each run lists the open issues and compares them with the record of the issues that Kairos took. An issue with no record becomes a task.

Field	Type	Required	Description
last_complete_at	string, nullable	no	When the last complete run ended (RFC 3339).
last_error	string, nullable	no	Why the last run stopped, or None. The next run tries again.
last_error_at	string, nullable	no	When that error happened (RFC 3339).
last_run_at	string, nullable	no	When the last run ended, complete or not (RFC 3339).
last_run_complete	boolean	no	True: the last run listed every page. False: it stopped half way, or it has not ended. The next run goes on.
last_run_imported	integer	no	The tasks that the last run made.
last_run_listed	integer	no	The open issues that the last run listed.
next_run_at	string, nullable	no	When the next run is due (RFC 3339). None: the cadence is off, or the first run is due now.
record_count	integer	no	The issues in the record: those that Kairos took for the repository.

ItemActivityEntry

One row of the activity of one item, as returned by GET /api/{entity_type}/{short_code}/activity (KAIROS-T-0557).

Field	Type	Required	Description
action	string	yes	The action of the row, as in [ActivityEntry::action].
actor_id	string	yes	Who did it (user UUID).
actor_name	string, nullable	no	The display name of the actor. Null for an actor that Kairos does not know.
agent_key_id	string, nullable	no	The agent key (UUID) of the request, when an agent made the change with the agent key of a person (KAIROS-T-0359). Show “Alice (agent)”.
details	string	yes	The details of the row, as they are stored.
id	string	yes	Row id (UUID).
occurred_at	string	yes	RFC 3339.
text	string	yes	The row as one line of text, with the names of the people, the boards, the columns and the repositories instead of their ids, for example moved from Todo to Active or claim taken: Alice.

ItemExternalRefsResponse

Response of GET /api/{entity_type}/{short_code}/external.

Field	Type	Required	Description
external	array of ExternalRef	yes	The references of the item, oldest first.
short_code	string	yes	The short code of the item.

ItemImpactsResponse

Response of GET /api/{entity_type}/{short_code}/impacts.

Field	Type	Required	Description
impacts	array of Impact	yes	The impacts links of the item, by the slug of the repository.
short_code	string	yes	The short code of the item.

ItemLink

One branch or pull/merge request linked to a work item.

Field	Type	Required	Description
author	string	yes
external_id	string	yes	PR/MR number, or the branch ref.
forge	string	yes	`github
forge_updated_at	string	yes	The forge’s own last-update time, RFC 3339.
id	string	yes	Link id (UUID).
item_id	string	yes	The linked work item (UUID).
kind	string	yes	`branch
repo_full_name	string	yes	owner/repo (from the owning connection).
state	string	yes	`open
title	string	yes
url	string	yes	Browser URL on the forge.

ItemMetadataResponse

Response of GET/PATCH /api/{entity_type}/{short_code}/metadata.

Field	Type	Required	Description
short_code	string	yes	The item the values belong to.
values	array of MetadataValue	yes	All metadata values on the item, ordered by definition slug.

ItemNote

One note of an item (KAIROS-T-0630): a row of its own, not part of the content of the item.

Field	Type	Required	Description
author	string	yes	The name of the author: the display name of the user, or the name of an old note as written.
author_id	string, nullable	no	The user that wrote the note (UUID). Absent for an old note whose name is no user of the organization.
author_user_name	string, nullable	no	The user name of the author (KAIROS-T-0665). Absent when the note has no user.
created_at	string	yes	RFC 3339.
id	string	yes	The id of the note in its item: n-3. Cite it as note n-3 on ACME-T-0012.
promoted_to	string, nullable	no	The short code of the draft ADR or document that a promote made from the note. Absent until then. A note is promoted once.
text	string	yes	The markdown text. It can have headings.

ItemOwner

The owner of a strategy or an initiative (KAIROS-T-0411): the one person who answers for the item. A member of the board claims an item with no owner. The owner hands it off. An organization admin sets or clears it. The owner gives no right.

Field	Type	Required	Description
claimed_at	string	yes	When the person became the owner, RFC 3339.
display_name	string	yes	The display name of the person.
user_id	string	yes	The person (UUID).

ItemOwnerResponse

Response of GET /api/{entity_type}/{short_code}/owner and of the changes of the owner (KAIROS-T-0411).

Field	Type	Required	Description
owner	ItemOwner, nullable	no
short_code	string	yes	The short code of the strategy or the initiative.

ItemRelationshipsResponse

Response of GET /api/{entity_type}/{short_code}/relationships: both directions, grouped by relationship type.

Field	Type	Required	Description
incoming	array of RelationshipGroup	yes	Edges where the item is the TARGET (the neighbor is the source, e.g. its parent via parent, items blocking it via blocks).
outgoing	array of RelationshipGroup	yes	Edges where the item is the SOURCE (the neighbor is the target, e.g. children via parent, items it blocks via blocks).
short_code	string	yes	The item the relationships belong to.

ItemTeam

One team of an initiative or a strategy (KAIROS-T-0321). The item gets the team from its tasks, or a person sets it by hand, or both. A task gives the team of its board. A strategy reads two levels down. A team gives no right on the item.

Field	Type	Required	Description
from_tasks	boolean	yes	The item gets the team from its tasks.
name	string	yes	The name of the team.
set_by_hand	boolean	yes	The team is set on the item by hand.
slug	string	yes	The slug of the team.

ItemTeamsResponse

Response of GET /api/{entity_type}/{short_code}/teams (KAIROS-T-0321).

Field	Type	Required	Description
short_code	string	yes	The short code of the item.
teams	array of ItemTeam	yes	The teams of the item, by slug. Empty when the item has no team.

ItemWatcher

One watcher of an item (KAIROS-T-0762), in GET /api/items/{short_code}/watchers.

Field	Type	Required	Description
added_by	string	yes	Who added the watch (UUID): the watcher for a self-watch.
added_by_name	string, nullable	no	The display name, else the user name, of who added the watch.
can_remove	boolean	yes	true when the caller can remove this watch: the caller is the watcher, or added the watch.
created_at	string	yes	When the watch started (RFC 3339).
display_name	string	yes
user_id	string	yes	The watcher (UUID).
user_name	string	yes
with_children	boolean	yes	true when the watch includes the children of the item.

ItemWatchers

GET, PUT and DELETE /api/items/{short_code}/watchers... response (KAIROS-T-0762): each person who watches the item, oldest watch first. A person who watches a parent with its children is not in the list.

Field	Type	Required	Description
short_code	string	yes	The code of the item.
watchers	array of ItemWatcher	yes

JobFailure

A job that failed, with its error.

Field	Type	Required	Description
error	string, nullable	no	The reason of the failure, cut to [JOB_ERROR_LIMIT] characters.
finished_at	string, nullable	no	When the job failed, RFC 3339.
id	string	yes	The id of the job (a UUID).
kind	string	yes
max_tries	integer	yes
tenant	string, nullable	no	The slug of the organization; absent for a job of the deployment.
tries	integer	yes

JobKindCounts

The jobs of one kind in each state.

Field	Type	Required	Description
done	integer	yes	The jobs that ended well and are kept for a time.
failed	integer	yes	The jobs that failed and are kept for a time.
kind	string	yes	The kind of job: hosted_build, webhook_delivery, periodic, and the others.
leased	integer	yes	The jobs that a server runs now.
queued	integer	yes	The jobs that wait for a server.

JobQueueStatus

GET /api/admin/jobs (KAIROS-T-0576): the job queue of the organization and of the deployment.

Field	Type	Required	Description
failures	array of JobFailure	yes	The failed jobs, newest first, at most [JOB_FAILURE_LIMIT].
kinds	array of JobKindCounts	yes	The jobs of each kind in each state, by kind. A finished job stays for 7 days.

KeyScopeBoard

One board of a [KeyScopeView].

Field	Type	Required	Description
id	string	yes
slug	string, nullable	no	The slug of the board; null when the board is deleted.

KeyScopeRequest

The scope of a new agent key (KAIROS-T-0536). A scope never adds a right. The key does an action when the person can do it and the scope has it.

Field	Type	Required	Description
boards	array, nullable	no	The boards where the key can act, by slug or id. Omitted: each board. With a list, an action that has no board is refused.
capabilities	array, nullable	no	The capabilities of the key, from the vocabulary of the capabilities reference: the board capabilities, manage_structure and file_backlog. [] makes a read-only key. Omitted: the default list (each one but purge and manage_structure).

The server refuses a body with a field that is not in this table (Errors).

KeyScopeView

The scope of a key (KAIROS-T-0536). null in place of this object: the key has no scope and no limit (a key made before KAIROS-T-0536).

Field	Type	Required	Description
boards	array, nullable	no	The boards of the key. null: each board.
capabilities	array of string	yes	The capabilities of the key, sorted. Empty: a read-only key.

ListEnvelope_ActivityEntry

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Adr

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Board

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_CodeIndex

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_DeliveryStream

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Document

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_HistoryVersion

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Initiative

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_ItemActivityEntry

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_MetadataDefinition

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_OrgAgentKey

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_OrgMember

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Repository

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Strategy

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Task

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Team

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_TeamAnnouncement

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_TeamPageVersionSummary

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_Template

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

ListEnvelope_TenantSummary

The S-0005 list envelope: {items, total, limit, offset}.

Field	Type	Required	Description
items	array of object	yes
limit	integer	yes	The applied limit.
offset	integer	yes	The applied offset.
total	integer	yes	Rows matching the request, ignoring pagination. Live rows only unless the request asked for archived work as well — total and items always answer the same question (KAIROS-T-0159). The activity feed counts at most past the larger of 1000 and offset + limit (KAIROS-T-0627): a total above that bound means “more than the bound”.

LocalAccountView

POST /api/local-accounts 201 body.

Field	Type	Required	Description
created	boolean	yes	True when a new person was created; false when a password was added to an existing row (an OIDC identity for the same email — KAIROS-T-0197).
display_name	string	yes
email	string	yes
membership_added	boolean	yes	True when this call added the org membership; false when they were already a member.
user_id	string	yes

LoginRequest

POST /api/login body.

Field	Type	Required	Description
email	string	yes	The account’s email address. Matched case-insensitively.
password	string	yes

The server refuses a body with a field that is not in this table (Errors).

LoginResponse

POST /api/login 200 body. The token is returned EXACTLY ONCE — only its SHA-256 is stored.

Field	Type	Required	Description
expires_at	string	yes	When it stops working (RFC 3339).
token	string	yes	The session bearer (kairos_ss_<64-hex>). Present it as Authorization: Bearer <token>.
user	LoginUser	yes	Who it authenticates, so a client need not immediately call /api/whoami.

LoginUser

The user object of [LoginResponse].

Field	Type	Required	Description
display_name	string	yes
email	string	yes
id	string	yes

MarkNotificationsReadRequest

POST /api/me/notifications/read body: ids, or all: true with up_to. Not both.

Field	Type	Required	Description
all	boolean, nullable	no	true: each unread notification of the caller up to up_to.
ids	array, nullable	no	The ids of notifications of the caller.
up_to	string, nullable	no	With all: true, required: the id of the newest notification that the caller read. Kairos marks it and each older unread one, and no newer one (KAIROS-T-0550).

The server refuses a body with a field that is not in this table (Errors).

MarkNotificationsReadResponse

POST /api/me/notifications/read response.

Field	Type	Required	Description
marked	array of string	yes	The ids that changed from unread to read.
unread	integer	yes	The count of the unread notifications after the change.

MetadataDefinition

A metadata field definition, as returned by /api/metadata-definitions.

Field	Type	Required	Description
created_at	string	yes	RFC 3339.
entity_types	array of string	yes	Entity types this definition applies to (KAIROS-T-0078): `strategy
enum_options	array of string	yes	Allowed values in display order (empty unless field_type = enum).
field_type	string	yes	`string
id	string	yes	Definition id (UUID).
is_system_default	boolean	yes	Seeded from the system defaults at tenant provisioning.
name	string	yes
slug	string	yes
updated_at	string	yes	RFC 3339.

MetadataValue

One typed metadata value on an item, hydrated with its definition.

Field	Type	Required	Description
definition_id	string	yes	metadata_definitions.id (UUID).
field_type	string	yes	`string
name	string	yes	The definition’s display name.
slug	string	yes	The definition’s slug (the PATCH key).
value	string	yes	The stored value.

MoveTaskRequest

Body of POST /api/tasks/{short_code}/move (KAIROS-I-0012): the delivery board to move the task to, by slug or UUID. It lands in that board’s entry column and follows its team.

Field	Type	Required	Description
board	string	yes
rename	boolean	no	Give the task the next code of the target board (COLLIERY-T-3101). Kairos retires the old code. The references to it change one time.

The server refuses a body with a field that is not in this table (Errors).

MutedKey

An agent key that the caller muted (KAIROS-T-0737).

Field	Type	Required	Description
id	string	yes	The id of the key (UUID).
name	string	yes	The name of the key.
owner_id	string	yes	The person of the key (UUID).
owner_name	string	yes	The name of the person of the key.
prefix	string	yes	The display prefix of the key.

MyWork

GET /api/me/work response: the two lanes of the work of the caller.

Field	Type	Required	Description
initiatives	array of WorkItem	yes	The strategies and the initiatives that the caller owns, by short code.
tasks	array of WorkItem	yes	The tasks that the caller (or an agent key of the caller) has the claim on; the tasks in Todo, Active or Blocked under an initiative that the caller owns; and the tasks that one of these blocks. By short code.

NearestCodeIndex

The answer to GET /api/repositories/{slug}/code-indexes/nearest.

Field	Type	Required	Description
distance	integer	yes	The commits from the indexed commit to from. 0 when from has an index.
from	string	yes	The commit that the request gave.
index	CodeIndex	yes	The nearest indexed commit at or below from.

NotReached

One live descendant that an archive does not reach (COLLIERY-T-0234). The archive stops at a descendant that the caller cannot edit, and takes nothing below it. An entry has one of two reasons. required_capability, with board_id: the caller cannot edit this item. below: this item is below the named item, where the archive stopped.

Field	Type	Required	Description
below	string, nullable	no	The short code of the item above this one where the archive stopped.
board_id	string, nullable	no	The authorization board of the descendant (UUID).
required_capability	string, nullable	no	The manage_<type> capability that the caller does not hold.
short_code	string	yes	The short code of the descendant.

Notification

One notification of the caller (KAIROS-T-0382).

Field	Type	Required	Description
actor_id	string, nullable	no	The person or the service account that made the change (UUID).
agent_key_id	string, nullable	no	The agent key that made it (UUID): a notice from an agent (KAIROS-T-0737). null: a person, or Kairos.
agent_key_name	string, nullable	no	The name of that agent key.
created_at	string	yes	When Kairos made the notification (RFC 3339).
entity_type	string, nullable	no	`strategy
id	string	yes	The id (UUID). POST /api/me/notifications/read takes it.
kind	string	yes	`hand_off
read_at	string, nullable	no	When the person read it (RFC 3339); null while unread.
short_code	string, nullable	no	The code of the item now; null when the item is gone.
text	string	yes	What happened, in one sentence or two.
title	string, nullable	no	The title of the item now; null when the item is gone.

NotificationList

GET /api/me/notifications response: each unread notification (newest first, 100 at most), then the 20 newest read ones.

Field	Type	Required	Description
items	array of Notification	yes
unread	integer	yes	The count of all the unread notifications of the caller.

NotificationSettings

GET and PUT /api/me/notification-settings response: each kind, and whether it is on. A kind that is off makes no notification for the person.

Field	Type	Required	Description
agent_key_revoked	boolean	yes	An organization admin revoked an agent key of yours (KAIROS-T-0388).
blocked_again	boolean	yes	A blocker of an item that you have the claim on (or own, or made) left a done column, so it blocks again (KAIROS-T-0568).
blocker_cancelled	boolean	yes	A person cancelled a task that blocks an item that you have the claim on, own or made. The cancelled task still blocks (KAIROS-T-0567).
blocker_cleared	boolean	yes	A blocker of an item that you have the claim on (or own) is done, archived or purged, or its blocks link is removed.
cancelled	boolean	yes	A person cancelled a task that you created.
claim_dropped	boolean	yes	A person left the organization, so their claim on a task of the board of your team ended. The task is free (KAIROS-T-0531).
claim_stale	boolean	yes	A claim had no write and no state change for some days: your claim, or a claim on a task of an initiative that you own (KAIROS-T-0531).
delivery_failing	boolean	yes	A webhook target that you own was turned off after failed deliveries (KAIROS-T-0384).
hand_off	boolean	yes	A person handed off the claim of a task to you.
key_expiring	boolean	yes	An agent key of yours, or a key of a service account of your organization (you are an admin), expires within 7 days (KAIROS-T-0540).
mention	boolean	yes	A person wrote @your_user_name in a note or in the content of an item.
muted_keys	array of MutedKey	yes	The agent keys that you muted: a notice from one of them, or from a key that replaced one of them, makes no notification for you (KAIROS-T-0737).
notice	boolean	yes	A person, or an agent key of a person, sent you a notice: to you, or to a team of yours (KAIROS-T-0737).
p0_bug	boolean	yes	A bug with the priority P0 (critical) is on the board of your team.
proposal_decided	boolean	yes	A person confirmed or rejected an edge proposal that you made (KAIROS-T-0558).
watch	boolean	yes	An item that you watch, or a child of an item that you watch with its children, moved, was edited, got a note, or is done (KAIROS-T-0736).

OrgAgentKey

One agent key of a person, as an organization admin reads it (KAIROS-T-0388). Never the secret.

Field	Type	Required	Description
created_at	string	yes
expires_at	string, nullable	no	null: the key never expires.
id	string	yes	The key id (UUID). DELETE /api/org/agent-keys/{key_id} takes it.
last_used_at	string, nullable	no
name	string	yes
owner_email	string	yes	The email of the owner.
owner_id	string	yes	The user id (UUID) of the person who owns the key.
owner_name	string	yes	The display name of the owner.
prefix	string	yes	The start of the key (never the secret).
replaced_by	string, nullable	no	The key that a rotation made in place of this key (KAIROS-T-0370).
revoked_at	string, nullable	no	null while the key is not revoked.

OrgDeleteResponse

Generic delete acknowledgement for organizational resources (boards, columns, transitions, teams, streams, membership rows).

Field	Type	Required	Description
deleted	boolean	yes
id	string	yes	Id of the deleted resource (UUID).

OrgMember

An organization member (GET /api/members element).

Field	Type	Required	Description
display_name	string	yes
email	string	yes
external_id	string	yes	OIDC sub.
joined_at	string	yes	RFC 3339.
role	string	yes	`admin
user_id	string	yes	public.users.id (UUID).

OrgReadToken

The read token of the organization for one forge host (KAIROS-T-0431). A read shows the host, who set it and when. It never shows the token.

Field	Type	Required	Description
host	string	yes	The host in lowercase, with :port only when the port is not the default, for example github.com.
set_at	string	yes	RFC 3339.
set_by	string	yes
set_by_name	string, nullable	no	The display name of set_by, else the email.

OrganizationDictionary

GET /api/org/dictionary (KAIROS-T-0734, KAIROS-A-0079): the dictionary of the organization. An organization has one dictionary, on the board strategy; there are no team dictionaries.

Field	Type	Required	Description
problems	array of DictionaryProblem	yes	The bad rows of the dictionary. A bad row gives no term.
short_code	string, nullable	no	The short code of the dictionary document; null when the organization has no dictionary.
terms	array of DictionaryTerm	yes	Each term, sorted by the word (case ignored).

PlaceTeamItemRequest

Body of PUT /api/teams/{id}/tree-items/{item} (KAIROS-T-0437).

Field	Type	Required	Description
parent_id	string, nullable	no	The folder (a team page id); null or absent puts it at the root.
position	integer	yes	Its position among its siblings.

The server refuses a body with a field that is not in this table (Errors).

ProgressCounts

A (done, total) children rollup (KAIROS-T-0080). done counts the children sitting in is_done columns. An archived child counts by the column that it was archived from (KAIROS-T-0571).

Field	Type	Required	Description
cancelled	integer	yes	Cancelled tasks among the children (KAIROS-T-0567). The default is for the client only: a response of an older server has no cancelled.
done	integer	yes	Children in a done column, less the cancelled tasks (KAIROS-T-0567).
has_done	boolean	yes	False when no board hosting the children has a done-flagged column — clients show composition only, never a done fraction. The server sends it in each response, so the schema shows it as required (COLLIERY-T-0254). The default is for the client only: a response of an older server has no has_done, and it reads as false.
open	integer	yes	Children that are not done and not cancelled.
removed	integer	yes	Children archived from a column that is not done (KAIROS-T-0571): not open work, and not in total. The default is for the client only.
total	integer	yes

PromoteNoteRequest

Body of POST /api/{entity_type}/{short_code}/notes/{note_id}/promote (KAIROS-T-0505): turn a note into a draft ADR or document.

Field	Type	Required	Description
board	string	yes	The board that gets the new item (slug or UUID). An ADR board for an ADR; the owner board for a document.
kind	string	yes	adr or document.
title	string, nullable	no	The title of the new item. Default: the first line of the note.

The server refuses a body with a field that is not in this table (Errors).

PromoteNoteResponse

Response of POST /api/{entity_type}/{short_code}/notes/{note_id}/promote (KAIROS-T-0505).

Field	Type	Required	Description
kind	string	yes	adr or document.
note_id	string	yes	The id of the note: n-3.
promoted_to	string	yes	The short code of the new item.
short_code	string	yes	The short code of the source item.
supports	boolean	yes	True when the new item supports the source item. False for a note on a document or an ADR: no edge joins two attachments.

ProposedRelationship

The answer of POST /api/relationships when the call made a proposal and no edge (202, KAIROS-T-0569). A blocks edge needs the right to edit the target. A caller who can edit the source only gets this.

Field	Type	Required	Description
message	string	yes	What the call did, and who can confirm the proposal.
proposal	EdgeProposalDto	yes	The proposal. Confirm it with POST /api/proposals/{id}/confirm.

PurgeTaskResponse

Response of POST /api/tasks/{short_code}/purge (KAIROS-T-0362): the task that is gone for good.

Field	Type	Required	Description
short_code	string	yes	The short code of the deleted task.
title	string	yes	The title of the deleted task.

PutCodeIndexSettings

Body of PUT /api/org/code-index-settings (an organization admin).

Field	Type	Required	Description
concurrency	integer, nullable	no	1 to 32. Not given: the value stays.
default_summaries	CodeIndexSummaries, nullable	no
summary	PutSummaryProvider, nullable	no
vectors	PutVectorProvider, nullable	no
version	integer, nullable	no	The version that the write is based on (KAIROS-T-0415). When it is not the stored version, the write is refused (409) and nothing changes. The web app and the CLI always send it.

The server refuses a body with a field that is not in this table (Errors).

PutSummaryProvider

The summaries part of PUT /api/org/code-index-settings. secret absent keeps the stored secret; an empty secret removes it; a value replaces it. For bedrock the secret is <access key id>:<secret access key> or <access key id>:<secret access key>:<session token>.

Field	Type	Required	Description
base_url	string, nullable	no
model	string, nullable	no
provider	string	yes
region	string, nullable	no
secret	string	no

The server refuses a body with a field that is not in this table (Errors).

PutVectorProvider

The vectors part of PUT /api/org/code-index-settings. The secret has the rules of [PutSummaryProvider::secret].

Field	Type	Required	Description
base_url	string, nullable	no
model	string, nullable	no
provider	string	yes
secret	string	no

The server refuses a body with a field that is not in this table (Errors).

QueryVector

The vector of a query, made by the model that made the vectors of the index (KAIROS-T-0360).

Field	Type	Required	Description
model	string	yes	The model of the request.
vector	array of number	yes	The vector: as many numbers as the dimension of the model.

QueryVectorRequest

Body of POST /api/code-index/query-vector (KAIROS-T-0360): the text of a code search, and the model of the vectors of the index.

Field	Type	Required	Description
model	string	yes	The model of the vectors of the index: <provider>/<model>/<dimension>, for example local/bge-small-en-v1.5-q/384.
text	string	yes	The text of the query: 1 to 2,000 characters.

The server refuses a body with a field that is not in this table (Errors).

RelatedItem

One hydrated neighbor of an item in the relationship graph.

Field	Type	Required	Description
archived_at	string, nullable	no	When this neighbour was archived, RFC 3339; absent while it is live. Relationship lists are archived-INCLUSIVE (KAIROS-T-0158): an item’s edges describe what it contains and depends on, and dropping an archived endpoint silently shrinks that answer. The row therefore comes back with this marker, and every renderer must show it — ADR-20: anything serving an archived row says so, or an auditor mistakes it for live work.
cancelled	boolean	no	true when the neighbour is a cancelled task (KAIROS-T-0567); absent otherwise. A cancelled task is in a done column, so done is true too. But a cancelled blocker is unresolved: it still blocks, and a client shows it as cancelled, not done.
done	boolean	no	true when this neighbour sits in a terminal column (a column the board marks is_done); absent otherwise (COLLIERY-T-0214). Done work does not block and is not blocked, so a blocks edge to a done neighbour is history, not an open blocker: the board’s blocks_summary does not count it. The edge still comes back here, because the list is the record, and every renderer of a blocks neighbour must show this marker. It follows the neighbour’s current column; nothing is stored.
entity_type	string	yes	`strategy
id	string	yes	The neighbor’s entity id (UUID).
relationship_id	string	yes	The edge’s id (UUID) — pass to DELETE /api/relationships/{id}.
short_code	string	yes	The neighbor’s short code.
title	string	yes	The neighbor’s title.

RelatedProposal

One related-work proposal: a claim, its evidence, and nothing asserted. There is no similarity here, deliberately. score is a fused rank and is comparable within one response only; a caller comparing it to a constant would be reading a number that has no fixed meaning. The measurements behind that are in kairos_core::retrieval.

Field	Type	Required	Description
claim	string	yes	implicit_dependency
entity_type	string	yes	Its entity type.
score	number	yes	Fused rank score. Comparable within this response and nowhere else.
short_code	string	yes	The proposed item’s short code.
title	string	yes	Its title.
why	string	yes	Why, in a sentence a person can disagree with.

RelatedWorkResponse

The answer to “what is related to this?”.

Field	Type	Required	Description
lexical	boolean	yes	Whether text search contributed.
note	string	yes	A sentence saying which of the two ran, for a caller that would rather read than branch.
proposals	array of RelatedProposal	yes	Bounded, best first. Possibly empty — which is one search coming up short, not proof that nothing is related.
short_code	string	yes	The item asked about.
vector	boolean	yes	Whether vector search contributed. False means a degraded answer: no embeddings yet, a model change, an unreachable provider. The answer is still useful; it will have missed work phrased differently.

Relationship

A relationship edge, as returned by POST /api/relationships.

Field	Type	Required	Description
created_at	string	yes	RFC 3339.
id	string	yes	Edge id (UUID).
relationship	string	yes	`parent
source_id	string	yes	Source entity id (UUID).
source_short_code	string	yes	The current short code of the source. A retired code in the request follows to its item (KAIROS-T-0560), so this code can differ from the request.
target_id	string	yes	Target entity id (UUID).
target_short_code	string	yes	The current short code of the target (see source_short_code).

RelationshipGroup

All of an item’s neighbors under ONE relationship type in one direction.

Field	Type	Required	Description
items	array of RelatedItem	yes	Hydrated neighbors, in edge-creation order.
relationship	string	yes	`parent

RemoveBoardMemberResponse

Response of DELETE /api/boards/{id}/members/{user_id} — full revocation of a user’s board membership.

Field	Type	Required	Description
revoked_capabilities	array of string	yes	The capabilities that were revoked (sorted).
user_id	string	yes	The user whose grants were revoked (UUID).

RemoveOrgMemberResponse

Response of DELETE /api/members/{user_id}.

Field	Type	Required	Description
removed	boolean	yes
user_id	string	yes	The removed member’s user id (UUID).

ReplaceCapabilitiesRequest

Body of PATCH /api/boards/{id}/members/{user_id} — replaces the user’s full capability set (revokes what is absent, grants what is new).

Field	Type	Required	Description
capabilities	array of string	yes	The complete new capability set (at least one; use DELETE to revoke board membership entirely).

The server refuses a body with a field that is not in this table (Errors).

Repository

One repository, as returned by /api/repositories (KAIROS-T-0106).

Field	Type	Required	Description
code_index_breaker	CodeIndexBreaker	no	The breaker of the code index builder of the repository (KAIROS-T-0399). A build job that stopped its server or stalled trips it. Then the builder starts no build of the repository. A requested build resets it.
code_index_build	CodeIndexBuild	no	Whether the code index builder works on the repository (KAIROS-T-0318): on (the default) or off.
code_index_scip_warnings	array of CodeIndexScipWarning	no	Each language with no SCIP index in the newest build of the code index that ended ok (KAIROS-T-0668): its edges are by name, and the reason says why. Empty when each SCIP indexer gave its index, and for a repository with no build.
code_index_summaries	CodeIndexSummaries	no	Where the summaries of the code index of the repository are made (KAIROS-T-0340): embedded, hosted, or organization (the default, KAIROS-T-0358): the default of the organization decides.
code_index_summaries_resolved	CodeIndexSummaries	no	Where the summaries are made now: embedded or hosted. For organization, the default of the organization (KAIROS-T-0358).
created_at	string	yes	RFC 3339.
credential	RepositoryCredential	no	The status of the read token of the repository (COLLIERY-T-3105). It never has the token.
default_branch	string	yes	The branch that the code index builder indexes (KAIROS-T-0430): the branch set by hand, or else the default branch of the forge at the last fetch. default_branch_source says which.
default_branch_source	DefaultBranchSource	no	Where default_branch comes from (KAIROS-T-0430): forge (the builder reads the default branch of the remote at each fetch) or hand (a person set it; it wins over the forge).
delivery_board_id	string, nullable	no	The delivery board of the owning team (UUID). It is a fact about the owner, not where tasks go: the board or the team of a task decides that (COLLIERY-T-0219, COLLIERY-A-0023). None only in a misconfigured tenant (team without a delivery board).
delivery_board_slug	string, nullable	no	The slug of that delivery board (KAIROS-T-0561), None when delivery_board_id is None.
description	string	yes	Short “how to work here” blurb agents read before starting.
forge	string	yes	`github
forge_branch	string, nullable	no	The default branch that the remote gave at the last fetch of the builder, or None before the first fetch (KAIROS-T-0430).
forge_filters	ForgeFilters	no	The forge filters of the repository (KAIROS-T-0479): the include and the exclude pattern of each field. Each field is present.
has_webhook	boolean	yes	Whether a live webhook connection exists for it.
id	string	yes	Repository id (UUID).
issue_import_interval	string	no	How often the repository takes its open issues with no webhook (KAIROS-T-0670): off (the default), or a number with a unit, such as 15m, 1h or 1d.
issue_import_interval_secs	integer, nullable	no	The same interval in seconds; None: off.
issue_sync	IssueSync	no	What the last runs of the import did (KAIROS-T-0670).
open_tasks	integer	yes	Live tasks that link to this repository and are not in a done column, on all boards of all teams (COLLIERY-T-0219).
repo_full_name	string	yes	owner/repo on GitHub, group/subgroup/project on GitLab.
repo_url	string	yes	Browser URL of the repository.
site	RepositorySite	no	The published site of the repository (KAIROS-T-0406).
slug	string	yes	Tenant-unique slug (^[a-z0-9][a-z0-9-]{1,62}$).
team	RepositoryTeam	yes	The one owning team.
updated_at	string	yes	RFC 3339.
write_back	RepositoryWriteBack	no	The GitHub write-back of the repository (KAIROS-T-0386): on when the repository has a write token. It never has the token.

RepositoryCredential

The status of the read token of a repository (COLLIERY-T-3105): what GET /api/repositories/{slug}/credential gives, and what each [Repository] carries. Kairos keeps the token encrypted, and no read gives it back.

Field	Type	Required	Description
last_check_error	string, nullable	no	The error of git at the last check, with the token removed.
last_check_ok	boolean, nullable	no	Whether git could read the repository with the token at the last check.
last_checked_at	string, nullable	no	When the last access check ran, RFC 3339. Null until a check runs for this token.
set	boolean	yes	Whether the repository has a read token.
set_at	string, nullable	no	When the token was set, RFC 3339.
set_by	string, nullable	no	The user who set the token (UUID).
set_by_name	string, nullable	no	The name of that user, else the email.

RepositoryDetail

GET /api/repositories/{slug}: the repository plus its webhook connection (id only — secrets are never re-read) and in-flight links. Until COLLIERY-T-0219 this also carried stale_tasks: linked tasks on a board of a team that does not own the repository. COLLIERY-A-0023 makes that normal work, so the field is removed. This is a wire change: a client that reads the field finds it absent.

RepositoryRef

The repository a task is bound to, embedded on [super::types::Task] so cards and agents get the slug without a second read.

Field	Type	Required	Description
forge	string	yes	`github
id	string	yes	Repository id (UUID).
repo_full_name	string	yes	owner/repo on GitHub, group/subgroup/project on GitLab.
slug	string	yes	Tenant-unique slug — what agents and the CLI address.
team_id	string	yes	Owning team (UUID).

RepositorySite

The site of a repository, on [crate::types_repositories::Repository].

Field	Type	Required	Description
base_path	string	yes	The path where Kairos serves the site, and the base path that its build must use, e.g. /pages/acme/platform/repos/payments-api/.
enabled	boolean	yes	The site switch. Off: a publish is refused, and the site is not served.
needs_republish	boolean	no	True when the live publish was built for a different base path (the repository moved to another team, or a slug changed): publish again.
published	SitePublish, nullable	no

RepositoryTeam

The owning team, embedded on [Repository].

Field	Type	Required	Description
id	string	yes	Team id (UUID).
name	string	yes
slug	string	yes

RepositoryWriteBack

The GitHub write-back of a repository (KAIROS-T-0386), as [Repository] carries it. With a write token, Kairos writes a comment and the status kairos on each linked pull request. Kairos keeps the token encrypted, and no read gives it back.

Field	Type	Required	Description
enabled	boolean	yes	True: the repository has a write token, and Kairos writes to GitHub.
last_write_at	string, nullable	no	When the last write ran, RFC 3339.
last_write_error	string, nullable	no	The error of the last write, with no token in it.
last_write_ok	boolean, nullable	no	Whether the last write worked.
set_at	string, nullable	no	When the token was set, RFC 3339.
set_by	string, nullable	no	The user who set the token (UUID).
set_by_name	string, nullable	no	The name of that user, else the email.

RestoreResponse

Response of POST /api/{entity_type}/{short_code}/restore (KAIROS-T-0160, KAIROS-A-0020): the archived item is live again. A restore deliberately does NOT un-cascade — a cascade delete was an act on a subtree, and resurrecting descendants would undo decisions nobody asked to revisit. The descendants still away are named here instead, so “I restored it and half of it is missing” is answered before it is asked.

Field	Type	Required	Description
short_code	string	yes	The restored item’s short code.
still_archived_count	integer	yes	How many of its descendants are still archived.
still_archived_short_codes	array of string	yes	Their short codes, sorted — restore them with further calls.

RetentionStatus

GET /api/org/retention: the retention settings of the deployment and the last retention pass. Never the path of the archive target.

Field	Type	Required	Description
activity_retention_days	integer	yes
archive_target	string, nullable	no	The kind of KAIROS_ARCHIVE_TARGET: filesystem or s3. Absent when no target is set.
history_hot_days	integer	yes
history_keep_latest	integer	yes
last_result	string, nullable	no	The record of the last pass that ended: skipped: no target, off or the counts. Absent before the first pass.
last_run_at	string, nullable	no	When the last pass ended, RFC 3339.
mode	string	yes	archive, discard or off (KAIROS_RETENTION_MODE).
status	string	yes	What a pass does: prunes, off, no_target (it removes no row) or target_not_implemented (each pass fails).
warning	string, nullable	no	The text for an operator when the pass removes nothing or fails.

ScimTokenCreatedResponse

POST /api/scim-tokens response — the ONLY place the secret appears.

Field	Type	Required	Description
created_at	string	yes
id	string	yes
name	string	yes
token	string	yes	The full bearer token. Shown once; store it in the IdP now.

ScimTokenListResponse

GET /api/scim-tokens envelope.

Field	Type	Required	Description
items	array of ScimTokenView	yes
total	integer	yes

ScimTokenRevokedResponse

DELETE /api/scim-tokens/{id} response.

Field	Type	Required	Description
id	string	yes
revoked	boolean	yes

ScimTokenView

One row of GET /api/scim-tokens — never a secret, never a hash.

Field	Type	Required	Description
created_at	string	yes
created_by	string	yes
id	string	yes
name	string	yes
revoked_at	string, nullable	no

SearchFilter

The filter capability. Fields are AND with each other; array values are OR within a field.

Field	Type	Required	Description
board	string, nullable	no	Restrict to items on this board, by slug or UUID (KAIROS-T-0368; excludes documents, which do not live on boards). Not with board_id.
board_id	string, nullable	no	The old name of board (KAIROS-T-0696): a UUID only. Kairos still accepts it; send board. Not with board.
claimed_by	string, nullable	no	Only the tasks that this person has the claim on (KAIROS-T-0488): a user id, an email, a user name, or me for the caller. A claim that an agent key of the person made counts. Other entity types are excluded. An unknown person is refused.
column	string, nullable	no	Restrict to items in this board column, by name (with board) or UUID (KAIROS-T-0552). Not with column_id.
column_id	string, nullable	no	The old name of column (KAIROS-T-0696): a UUID only. Kairos still accepts it; send column. Not with column.
created_after	string, nullable	no	Only items created strictly after this instant (RFC 3339).
created_before	string, nullable	no	Only items created strictly before this instant (RFC 3339).
created_by	string, nullable	no	Only the items that this person created (KAIROS-T-0488): a user id, an email, a user name, or me. An unknown person is refused.
entity_type	array, nullable	no	Restrict to these entity types (`strategy
include_deleted	boolean	no	Include archived (soft-deleted) items (default false). Composes with every other capability — q and traverse included since KAIROS-T-0157 — and is a complete request on its own. Archived hits are served with archived_at set (KAIROS-A-0020).
is_bucket	boolean, nullable	no	Restrict to (non-)bucket initiatives (initiative-level attribute; other entity types are excluded).
metadata	object, nullable	no	Metadata conditions keyed by definition slug; string values support trailing-* globs (e.g. "component": "auth*"). All entries must match (AND).
metadata_missing	array, nullable	no	Only items with NO value for each of these metadata definitions, by slug (KAIROS-T-0368): “bugs without a priority” is ["priority"]. An unknown slug is refused.
owned_by	string, nullable	no	Only the strategies and the initiatives that this person owns (KAIROS-T-0488): a user id, an email, a user name, or me. Other entity types are excluded. An unknown person is refused.
repository	string, nullable	no	Restrict to the items of this repository (slug or UUID of a live repository — KAIROS-T-0115 made every repository reference on the wire the same shape; the old name repository_id is refused, COLLIERY-T-0259). The items of a repository are the tasks that link to it, and the documents and the ADRs that impact it (COLLIERY-T-0269). Strategies and initiatives are excluded. With team_id, task_type or work_class, only tasks match.
task_type	array, nullable	no	Restrict to tasks of these types (`task
team	string, nullable	no	Restrict to tasks of this team, by slug or UUID (KAIROS-T-0368; a task-level attribute, other entity types are excluded). Not with team_id.
team_id	string, nullable	no	The old name of team (KAIROS-T-0696): a UUID only. Kairos still accepts it; send team. Not with team.
updated_after	string, nullable	no	Only items last changed strictly after this instant (RFC 3339, updated_at; KAIROS-T-0368).
updated_before	string, nullable	no	Only items last changed strictly before this instant (RFC 3339, updated_at; KAIROS-T-0368). “Untouched for 90 days” is now minus 90 days.
work_class	array, nullable	no	Restrict to tasks in these Planned/Support lanes (`planned

The server refuses a body with a field that is not in this table (Errors).

SearchRequest

Body of POST /api/search. All fields optional; at least one of q/filter/traverse must be present and constraining (400 VALIDATION otherwise).

Field	Type	Required	Description
filter	SearchFilter, nullable	no
limit	integer, nullable	no	Page size (default 25, max 100).
offset	integer, nullable	no	Offset into the combined result set (default 0).
q	string, nullable	no	Full-text search (PostgreSQL websearch semantics; quoted phrases, OR, -negation).
sort	SearchSort, nullable	no
traverse	SearchTraverse, nullable	no

The server refuses a body with a field that is not in this table (Errors).

SearchResponse

Response of POST /api/search: results grouped by entity type plus the pagination envelope. total counts matches BEFORE limit/offset are applied.

Field	Type	Required	Description
limit	integer	yes	The applied page size.
offset	integer	yes	The applied offset.
results	SearchResultGroups	yes	Matches grouped by entity type; empty groups are omitted from the JSON.
total	integer	yes	Total matches before pagination.

SearchResultGroups

The results object: one group of cards per entity type, each group omitted entirely when empty. Group order follows the request’s combined sort. A hit is a card (KAIROS-T-0602): the title and a snippet of the content, not the content. The item route of the hit gives the content.

Field	Type	Required	Description
adrs	array of AdrCard	no	Matching ADRs.
documents	array of DocumentCard	no	Matching documents.
initiatives	array of InitiativeCard	no	Matching initiatives.
strategies	array of StrategyCard	no	Matching strategies.
tasks	array of TaskCard	no	Matching tasks.

SearchSort

The sort clause, applied to the combined cross-type result set before pagination.

Field	Type	Required	Description
field	string	yes	`created_at
order	string	yes	`asc

The server refuses a body with a field that is not in this table (Errors).

SearchTraverse

The traverse capability: recursive walk of the relationship graph from a starting node.

Field	Type	Required	Description
depth	integer, nullable	no	Maximum traversal depth — required, 1..=10 (server-capped). Typed as optional so a missing depth is a field-level 400, not a parse error.
direction	string	yes	Edge direction(s) to walk (`outbound
from	SearchTraverseFrom	yes	The starting entity, identified by exactly one of short_code/id.
relationships	array of string	yes	Relationship types to follow (non-empty; `parent

The server refuses a body with a field that is not in this table (Errors).

SearchTraverseFrom

traverse.from: exactly one of short_code/id.

Field	Type	Required	Description
id	string, nullable	no	The starting entity’s id (UUID).
short_code	string, nullable	no	The starting entity’s short code (e.g. "ACME-S-0001").

The server refuses a body with a field that is not in this table (Errors).

SecretStatus

Whether a secret is set, and by whom. The secret itself never leaves the server.

Field	Type	Required	Description
set	boolean	yes
set_at	string, nullable	no	RFC 3339.
set_by	string, nullable	no
set_by_name	string, nullable	no	The display name of set_by (KAIROS-T-0415).

SectionCheck

The stored check of the typed sections of a document (KAIROS-T-0731, COLLIERY-I-0664 decision 3). Each content write of the document writes it, and a periodic pass checks the documents that no write checked. A document that does not pass gets this mark. The mark does not stop a write.

Field	Type	Required	Description
checked_at	string	yes	RFC 3339.
passes	boolean	yes	true when the document passes each typed section.
sections	array of SectionCheckFailure	yes	Each section that does not pass, in the order of the template.
stale	boolean	yes	The typed sections of the template or a dictionary changed after the check. The server checks the document again soon.
version	integer	yes	The version of the document that the server checked.
violations	integer	yes	The number of problems: 1 for each missing or empty section, and 1 for each violation of a plain or an ears section.

SectionCheckFailure

A typed section that a document does not pass (KAIROS-T-0731).

Field	Type	Required	Description
heading	string	yes	The heading of the section, with no #.
problem	string	yes	missing, empty or violations.
type	string	yes	The type of the section: free, plain or ears.
violations	array of SectionCheckViolation	no	The violations of a plain or an ears section; empty for the other problems.

SectionCheckViolation

One rule that the text of a section breaks (KAIROS-T-0731).

Field	Type	Required	Description
fix	string	yes	What is wrong, then what to do.
rule	string	yes	The rule id, as STE-V1 or EARS-1.
text	string	yes	The text that breaks the rule.

SendNoticeRequest

POST /api/notices body (KAIROS-T-0737): a notice to a person (to) or to each member of a team (team). Send one of the two.

Field	Type	Required	Description
short_code	string, nullable	no	The short code of a live item to link.
team	string, nullable	no	A live team: its slug or its UUID. Each member gets the notice.
text	string	yes	The text: 1 to 2000 characters.
to	string, nullable	no	A person of the organization: me, a UUID, an email or a user name.

The server refuses a body with a field that is not in this table (Errors).

SendNoticeResponse

POST /api/notices response (KAIROS-T-0737).

Field	Type	Required	Description
id	string	yes	The id of the notice (UUID).
remaining	integer, nullable	no	The notices that the sender can still send in this hour; null when the deployment has no limit.
told	array of string	yes	The persons who got a notification (UUIDs). A person who turned the kind notice off, or muted the key, is not in it.

ServiceAccountListResponse

GET /api/service-accounts envelope.

Field	Type	Required	Description
items	array of ServiceAccountView	yes
total	integer	yes

ServiceAccountView

A service account (never a secret).

Field	Type	Required	Description
created_at	string	yes
id	string	yes
name	string	yes

SessionListResponse

GET /api/local-accounts/{user_id}/sessions envelope.

Field	Type	Required	Description
items	array of SessionView	yes
total	integer	yes

SessionView

One session, for the audit listing. Never the token or its hash.

Field	Type	Required	Description
active	boolean	yes	Whether the session works right now — revocation and expiry collapsed, so a reader does not have to compare timestamps to answer the only question they actually have.
created_at	string	yes
expires_at	string	yes
id	string	yes
last_used_at	string, nullable	no	null until the session is first used.
revoked_at	string, nullable	no	null while the session is live.

SetAgentTriageRequest

PUT /api/boards/{id}/agent-triage body.

Field	Type	Required	Description
agents_decide	boolean	yes

The server refuses a body with a field that is not in this table (Errors).

SetComplexityRequest

Body of PUT /api/initiatives/{short_code}/complexity: set the complexity of an initiative. none clears it. The field is required, so a body that leaves it out cannot clear the complexity by mistake. Not content: no version bump (the A-0004 contract covers title/content only).

Field	Type	Required	Description
complexity	string	yes	`xs

The server refuses a body with a field that is not in this table (Errors).

SetDocumentBoardRequest

Body of PATCH /api/documents/{short_code}/board (COLLIERY-T-0269): change the owner board of a document. board is required. Its value is the slug or the id of a live board. Each document has an owner board (COLLIERY-T-3109), and you cannot remove it. The server refuses an absent, null or empty board: 422 VALIDATION, and details.field is board. The board that the document has changes nothing: the response is 200, and the server writes nothing.

Field	Type	Required	Description
board	string	yes	The new owner board (slug or UUID). An absent or null value reads as empty, so that the server gives the refusal that names board.
rename	boolean	no	COLLIERY-T-3101 (default false): the document also gets the next code of its new owner board. Kairos retires the old code and changes the references to it one time. A rename needs a new board.

The server refuses a body with a field that is not in this table (Errors).

SetItemTeamRequest

Body of POST /api/{entity_type}/{short_code}/teams (KAIROS-T-0321): the team to set on the item by hand.

Field	Type	Required	Description
team	string	yes	A live team of the organization, by slug or UUID.

The server refuses a body with a field that is not in this table (Errors).

SetLifecycleRequest

Body of POST /api/tasks/{short_code}/work-class (KAIROS-T-0077): move a task between the Planned/Support lanes. Orthogonal to column Body of PATCH /api/documents/{short_code}/lifecycle (KAIROS-T-0078): set the document’s editorial state. Free transitions; no version bump (the A-0004 contract covers title/content only).

Field	Type	Required	Description
lifecycle	string	yes	`draft

The server refuses a body with a field that is not in this table (Errors).

SetOrgReadTokenRequest

Body of PUT /api/org/read-tokens/{host} (KAIROS-T-0431, an organization admin): the read token of the organization for the host.

Field	Type	Required	Description
token	string	yes	The token. Kairos encrypts it, and no read gives it back.

The server refuses a body with a field that is not in this table (Errors).

SetParentRequest

Body of PUT /api/{entity_type}/{short_code}/parent (KAIROS-T-0572): set the parent of an initiative or a task, or remove it. An item has one parent, and the new edge replaces the old one in one transaction. parent is required: a short code, or null to remove the parent. A body without it is a 422, so that an empty body never removes a parent.

Field	Type	Required	Description
parent	string, nullable	yes	The short code of the new parent: a strategy for an initiative, an initiative for a task. A retired code finds its item. null removes the parent.

The server refuses a body with a field that is not in this table (Errors).

SetParentResponse

Response of PUT /api/{entity_type}/{short_code}/parent (KAIROS-T-0572).

Field	Type	Required	Description
changed	boolean	yes	false when the item had this parent already (or none, for null). Kairos then writes nothing.
parent	string, nullable	no	The parent now, by short code; null when the item has none.
previous_parent	string, nullable	no	The parent before the write, by short code; null when it had none.
short_code	string	yes	The short code of the item.

SetPasswordRequest

PUT /api/local-accounts/{user_id}/password body.

Field	Type	Required	Description
password	string	yes

The server refuses a body with a field that is not in this table (Errors).

SetRepositoryCredentialRequest

Body of PUT /api/repositories/{slug}/credential (COLLIERY-T-3105): the read token of the repository. Use a GitHub fine-grained personal access token with only “Contents: read” on the one repository.

Field	Type	Required	Description
token	string	yes	The token. Kairos encrypts it, and no read gives it back.

The server refuses a body with a field that is not in this table (Errors).

SetTaskRepositoryRequest

Body of PUT /api/tasks/{short_code}/repository — set the repository the task links to (slug or UUID), or clear it with null or an empty string (COLLIERY-T-0231). It can be any live repository, of any team. The board and the team of the task do not change (COLLIERY-T-0217, COLLIERY-A-0023).

Field	Type	Required	Description
repository	string, nullable	no

The server refuses a body with a field that is not in this table (Errors).

SetTaskStateRequest

Body of PUT /api/tasks/{short_code}/state (KAIROS-T-0506). Each field is optional. The write is a patch (KAIROS-T-0533): a field that you do not send keeps its value, null clears it. Send at least one field. expected_updated_at refuses a stale write with CONFLICT.

Field	Type	Required	Description
branch	string, nullable	no	The branch of the work. Absent: kept. null: cleared (KAIROS-T-0533).
commit	string, nullable	no	The last commit. Absent: kept. null: cleared.
expected_updated_at	string, nullable	no	The updated_at of the state you read (RFC 3339). A write against a state that changed since is refused with CONFLICT and the current state (KAIROS-T-0533).
next_step	string, nullable	no	What comes next. Absent: kept. null: cleared.
pr_url	string, nullable	no	The URL of the PR. Absent: kept. null: cleared.
pushed	boolean, nullable	no	True when the last commit is pushed. Absent: kept.

The server refuses a body with a field that is not in this table (Errors).

SetWorkClassRequest

transitions — the board rules engine is never consulted.

Field	Type	Required	Description
work_class	string	yes	`planned

The server refuses a body with a field that is not in this table (Errors).

SiteArchive

A site archive in the OpenAPI document: the bytes of a .tar.gz.

SitePublish

One publish of a site.

Field	Type	Required	Description
agent_key_id	string, nullable	no	The agent key that sent it (UUID), if one did.
base_path	string	yes	The base path the site was published for.
files	integer	yes	Entries of the archive (files and folders).
md5	string	yes	MD5 of the uploaded archive, lower-case hex.
principal_id	string	yes	The user or service account that sent it (UUID).
principal_name	string, nullable	no	Its display name (KAIROS-T-0408).
publish_id	string	yes	Publish id (UUID).
published_at	string	yes	RFC 3339.
repository_slug	string	yes	The slug of the repository at the time of the publish.
size	integer	yes	Bytes of the archive.
state	string	yes	live, replaced or unpublished.
unpacked_size	integer	yes	Bytes of the files.

Standup

GET /api/teams/{id}/standup response: the team and its people, for the round of a stand-up.

Field	Type	Required	Description
people	array of StandupPerson	yes	The people of the round, by display name: the members of the team, and each person who holds work of the team and is not a member. No service accounts.
team	StandupTeam	yes

StandupGroup

The group of an AdHoc stand-up (KAIROS-T-0764, KAIROS-A-0084): a saved, named group of people of the organization. Each stop shows the work of one person by ownership on each board. There is no Unclaimed stop.

Field	Type	Required	Description
can_delete	boolean	yes	true when the caller created the group, so the caller can delete it.
created_at	string	yes	RFC 3339.
created_by	StandupGroupPerson	yes	The person who created the group. Only this person can delete it.
id	string	yes	Group id (UUID).
name	string	yes	Unique in the organization, with no regard to case.
people	array of StandupGroupPerson	yes	The people of the round, by display name.
updated_at	string	yes	RFC 3339.

StandupGroupList

GET /api/standup-groups response: each group, by name.

Field	Type	Required	Description
items	array of StandupGroup	yes

StandupGroupPerson

A person of the group of an AdHoc stand-up (KAIROS-T-0764).

Field	Type	Required	Description
display_name	string	yes
user_id	string	yes	User id (UUID).
user_name	string	yes

StandupPerson

A person of the round of a stand-up.

Field	Type	Required	Description
display_name	string	yes
member	boolean	yes	A member of the team. false: a person who is not a member, and who claims a task of the team or owns an initiative of the team.
user_id	string	yes	User id (UUID).
user_name	string	yes

StandupTeam

The team of a stand-up.

Field	Type	Required	Description
id	string	yes	Team id (UUID).
name	string	yes
slug	string	yes

Strategy

A strategy (Flight Level 3), as returned by /api/strategies.

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live. Archiving hides work from default listings and nothing more (KAIROS-A-0020) — anything serving an archived row marks it, so an auditor never mistakes it for live work.
board_id	string	yes	Board the strategy sits on (UUID).
column_id	string	yes	Current column (UUID).
content	string	yes	Markdown content.
created_at	string	yes	RFC 3339.
created_by	string	yes	Creator user id (UUID).
hypothesis	string, nullable	no
id	string	yes	Entity id (UUID).
notes	array, nullable	no	The notes of the item, in the order of their ids (KAIROS-T-0630). Present on the read of one item (GET /api/{family}/{short_code}), empty when the item has none. Absent from lists and from the answers of writes. A note is not part of content.
owner	ItemOwner, nullable	no
short_code	string	yes	Tenant-scoped short code ({PREFIX}-S-{NNNN}).
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string	yes	Last editor user id (UUID).
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004); submit it back on PATCH.

StrategyCard

A strategy on a board or in a search (KAIROS-T-0602).

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live (KAIROS-A-0020).
board_id	string	yes	Board the strategy sits on (UUID).
column_id	string	yes	Current column (UUID).
content	string, nullable	no	Markdown content. Only with fields=full on the board route. A card has no notes (KAIROS-T-0630): the read of the item gives them.
created_at	string	yes	RFC 3339.
created_by	string, nullable	no	Creator user id (UUID). Only with fields=full on the board route.
entered_column_at	string, nullable	no	When the card entered its column, RFC 3339: its last move, or its creation (KAIROS-T-0649). Present on the board route; absent on a search hit.
hypothesis	string, nullable	no
id	string	yes	Entity id (UUID).
notes_count	integer, nullable	no	The number of the notes of the item (KAIROS-T-0649). Present on the board route; absent on a search hit.
owner	ItemOwner, nullable	no
short_code	string	yes	Tenant-scoped short code ({PREFIX}-S-{NNNN}).
snippet	string, nullable	no	About 200 characters of the content, near the first match of q. Only on a search hit.
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string, nullable	no	Last editor user id (UUID). Only with fields=full on the board route.
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).

StructureGrant

One grant of manage_structure (GET /api/structure-grants element). scope is organization or board. A grant on the organization covers teams, team members, boards and repositories. A grant on a board covers the configuration, the members and the grants of that board only.

Field	Type	Required	Description
board_id	string, nullable	no	The board of a board grant (UUID), or null.
board_slug	string, nullable	no	The slug of the board of a board grant, or null.
display_name	string	yes
email	string	yes
granted_at	string	yes	RFC 3339.
granted_by	string	yes	public.users.id of the organization admin who granted it.
id	string	yes	The id of the grant (UUID). DELETE /api/structure-grants/{id} revokes it.
kind	string	yes	human
scope	string	yes	organization
user_id	string	yes	public.users.id of the principal (UUID).

SummaryProviderSettings

Where the summaries of the code index are made.

Field	Type	Required	Description
base_url	string, nullable	no	The base URL of an OpenAI-compatible endpoint, for ollama-cloud.
model	string, nullable	no	The model to ask for: a model name for ollama-cloud, a model id for bedrock.
provider	string	yes	embedded (the model in the server), ollama-cloud (an OpenAI-compatible chat endpoint) or bedrock (AWS Bedrock).
region	string, nullable	no	The AWS region, for bedrock.
secret	SecretStatus	yes	The API key (ollama-cloud) or the AWS credentials (bedrock).

Task

A task/bug/tech-debt item (Flight Level 1), as returned by /api/tasks.

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live. Archiving hides work from default listings and nothing more (KAIROS-A-0020) — anything serving an archived row marks it, so an auditor never mistakes it for live work.
board_id	string	yes	Board the task sits on (UUID).
cancellation	TaskCancellation, nullable	no
claim	TaskClaim, nullable	no
column_id	string	yes	Current column (UUID).
content	string	yes	Markdown content.
created_at	string	yes	RFC 3339.
created_by	string	yes	Creator user id (UUID).
id	string	yes	Entity id (UUID).
notes	array, nullable	no	The notes of the item, in the order of their ids (KAIROS-T-0630). Present on the read of one item (GET /api/{family}/{short_code}), empty when the item has none. Absent from lists and from the answers of writes. A note is not part of content.
repository	RepositoryRef, nullable	no
repository_id	string, nullable	no	The repository this task is issued against (UUID), if bound (KAIROS-T-0104, A-0019).
short_code	string	yes	Tenant-scoped short code ({PREFIX}-T-{NNNN}).
state	TaskState, nullable	no
task_type	string	yes	`task
team_id	string, nullable	no	Owning team (UUID), if assigned.
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string	yes	Last editor user id (UUID).
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).
work_class	string	yes	Planned/Support lane (`planned

TaskCancellation

The cancel mark of a task (KAIROS-T-0362). A cancel moves the task to the done column of its board. A move out of the done column removes the mark; the history keeps the reason.

Field	Type	Required	Description
cancelled_at	string	yes	RFC 3339.
cancelled_by	string	yes	The person or the service account that cancelled the task (UUID).
cancelled_by_name	string	yes	The display name of cancelled_by.
reason	string	yes	Why the task is cancelled.

TaskCard

A task on a board or in a search (KAIROS-T-0602).

Field	Type	Required	Description
archived_at	string, nullable	no	When this work was put away, RFC 3339; absent while it is live (KAIROS-A-0020).
board_id	string	yes	Board the task sits on (UUID).
cancellation	TaskCancellation, nullable	no
claim	TaskClaim, nullable	no
column_id	string	yes	Current column (UUID).
content	string, nullable	no	Markdown content. Only with fields=full on the board route. A card has no notes (KAIROS-T-0630): the read of the item gives them.
created_at	string	yes	RFC 3339.
created_by	string, nullable	no	Creator user id (UUID). Only with fields=full on the board route.
entered_column_at	string, nullable	no	When the card entered its column, RFC 3339: its last move, or its creation (KAIROS-T-0649). Present on the board route; absent on a search hit.
id	string	yes	Entity id (UUID).
notes_count	integer, nullable	no	The number of the notes of the item (KAIROS-T-0649). Present on the board route; absent on a search hit.
repository	RepositoryRef, nullable	no
repository_id	string, nullable	no	The repository this task is issued against (UUID), if bound.
short_code	string	yes	Tenant-scoped short code ({PREFIX}-T-{NNNN}).
snippet	string, nullable	no	About 200 characters of the content, near the first match of q. Only on a search hit.
state	TaskState, nullable	no
task_type	string	yes	`task
team_id	string, nullable	no	Owning team (UUID), if assigned.
title	string	yes
updated_at	string	yes	RFC 3339.
updated_by	string, nullable	no	Last editor user id (UUID). Only with fields=full on the board route.
version	integer	yes	Optimistic-concurrency version (KAIROS-A-0004).
work_class	string	yes	Planned/Support lane (`planned

TaskClaim

The claim of a task (KAIROS-T-0359, KAIROS-A-0024): the person who has the task in Active. A task gets a claim when a person moves it to Active. It loses the claim when it leaves Active, at a hand-off to a different person, or at a release.

Field	Type	Required	Description
agent	boolean	no	True when the person’s agent made the claim with the agent key of the person.
claimed_at	string	yes	RFC 3339.
display_name	string	yes	The display name of the person.
user_id	string	yes	The person (UUID).
user_name	string	no	The user name of the person: write @<user name> to mention the person (KAIROS-T-0665). An older server does not send it.

TaskState

The live state of a task (KAIROS-T-0506): one current state, separate from the append-only notes. An agent writes it after each push and before each stop. A write is a patch (KAIROS-T-0533).

Field	Type	Required	Description
branch	string, nullable	no	The branch of the work.
commit	string, nullable	no	The last commit (a hash or a short hash).
next_step	string, nullable	no	What comes next.
pr_url	string, nullable	no	The URL of the PR.
pushed	boolean	no	True when the last commit is pushed.
updated_at	string	yes	RFC 3339.
updated_by	string	yes	The user id (UUID) of who wrote the state.
updated_by_name	string	yes	The display name of who wrote the state.

Team

A team (/api/teams). Every team owns a delivery board (KAIROS-A-0002/T-0010: created with the team from the system delivery defaults).

Field	Type	Required	Description
created_at	string	yes	RFC 3339.
delivery_board_id	string, nullable	no	The team’s delivery board (UUID); created with the team.
id	string	yes	Team id (UUID).
name	string	yes
site_enabled	boolean	no	The docs site of the team is on (KAIROS-T-0404).
slug	string	yes
team_type	string	yes	`stream_aligned
updated_at	string	yes	RFC 3339.

TeamAnnouncement

One team announcement (append-only; no edit anywhere).

Field	Type	Required	Description
body	string	yes	Markdown body.
created_at	string	yes	RFC 3339.
created_by	string	yes	Author user id (UUID).
id	string	yes	Announcement id (UUID).
pinned	boolean	yes	Pinned announcements sort first.
team_id	string	yes	Owning team (UUID).

TeamLink

One row of a team’s in-flight rollup (KAIROS-T-0101): a link plus the work item it belongs to, so the panel can link both to the forge and back into Kairos.

Field	Type	Required	Description
author	string	yes
external_id	string	yes	PR/MR number, or the branch ref.
forge	string	yes	`github
forge_updated_at	string	yes	RFC 3339.
item_short_code	string	yes	The Kairos work item this link belongs to.
item_title	string	yes
kind	string	yes	`branch
repo_full_name	string	yes	owner/repo.
state	string	yes	`open
title	string	yes
url	string	yes	Browser URL on the forge.

TeamMember

A team member (GET /api/teams/{id}/members element).

Field	Type	Required	Description
display_name	string	yes
email	string	yes
joined_at	string	yes	RFC 3339.
user_id	string	yes	public.users.id (UUID).
user_name	string	no	The user name: write @<user name> to mention the person (KAIROS-T-0665). An older server does not send it.

TeamPage

One node of a team’s page tree with its content, as returned by GET /api/teams/{id}/pages/{page_id} and by each write. The list of the tree has [TeamPageSummary] rows, with no content (KAIROS-T-0629).

Field	Type	Required	Description
content	string	yes	Markdown content (empty for folders).
created_at	string	yes	RFC 3339.
id	string	yes	Page id (UUID).
is_protected	boolean	yes	The Charter: content-editable, never renamed/moved/deleted.
kind	string	yes	`folder
parent_id	string, nullable	no	Parent folder (UUID); null for roots.
position	integer	yes	Display order among siblings.
slug	string	yes	URL segment, unique among siblings.
team_id	string	yes	Owning team (UUID).
title	string	yes
updated_at	string	yes	RFC 3339.
version	integer	yes	Optimistic-concurrency version (content edits only).

TeamPageSummary

One node of a team’s page tree without its content, as returned by GET /api/teams/{id}/pages (a FLAT list — clients nest by parent_id, ordered by position then title). Read the content with GET /api/teams/{id}/pages/{page_id} (KAIROS-T-0629).

Field	Type	Required	Description
created_at	string	yes	RFC 3339.
id	string	yes	Page id (UUID).
is_protected	boolean	yes	The Charter: content-editable, never renamed/moved/deleted.
kind	string	yes	`folder
parent_id	string, nullable	no	Parent folder (UUID); null for roots.
position	integer	yes	Display order among siblings.
slug	string	yes	URL segment, unique among siblings.
team_id	string	yes	Owning team (UUID).
title	string	yes
updated_at	string	yes	RFC 3339.
version	integer	yes	Optimistic-concurrency version (content edits only).

TeamPageVersionSummary

One row of the version list of a page (KAIROS-T-0439, KAIROS-T-0629): GET /api/teams/{id}/pages/{page_id}/history, newest first. It has no content: ?version=N gives one version in full ([TeamPageVersion]).

Field	Type	Required	Description
agent_key_id	string, nullable	no	The agent key (UUID) of the request that saved it, when an agent saved it with the agent key of the person: show “Alice (agent)”. Null otherwise.
edited_at	string	yes	RFC 3339.
edited_by	string	yes	The user id (UUID) of the person who saved it.
edited_by_name	string	yes	The display name of that person.
title	string	yes	The title at this version.
version	integer	yes

TeamTreeItem

One document or ADR in the tree of a team (KAIROS-T-0437): GET /api/teams/{id}/tree-items. Each document and ADR whose owner board is a board of the team. The board owns it; this is where it sits in the tree.

Field	Type	Required	Description
entity_type	string	yes	document or adr.
item_id	string	yes	The item id (UUID).
parent_id	string, nullable	no	Its folder (a team page id); null is the root.
position	integer, nullable	no	Its position among its siblings; null when nobody placed it (it shows at the end of the root).
short_code	string	yes
status	string	yes	The lifecycle of a document, or the column of an ADR.
title	string	yes

Template

A document template, as returned by GET /api/templates.

Field	Type	Required	Description
content	string	yes	Starter markdown content.
created_at	string	yes	RFC 3339.
id	string	yes	Template id (UUID).
is_system_default	boolean	yes	Seeded from the system defaults at tenant provisioning.
name	string	yes
slug	string	yes
updated_at	string	yes	RFC 3339.

TemplateDetail

Response of GET /api/templates/{id}: the template plus its associated metadata definitions with defaults/required flags.

Field	Type	Required	Description
content	string	yes	Starter markdown content.
created_at	string	yes	RFC 3339.
id	string	yes	Template id (UUID).
is_system_default	boolean	yes
metadata	array of TemplateMetadataField	yes	The metadata fields this template carries, ordered by slug.
name	string	yes
sections	array of TemplateSection	no	The typed sections of the template, in the order that the admin sent (KAIROS-T-0729).
slug	string	yes
updated_at	string	yes	RFC 3339.

TemplateMetadataEntry

One template ↔ metadata-definition association in a template write.

Field	Type	Required	Description
default_value	string, nullable	no	Optional default, validated against the definition’s type.
definition_slug	string	yes	Slug of an existing metadata definition. KAIROS-T-0696: the server also accepts the name definition, the name on MCP.
required	boolean	no

The server refuses a body with a field that is not in this table (Errors).

TemplateMetadataField

One metadata field a template carries (template_metadata hydrated with its definition).

Field	Type	Required	Description
default_value	string, nullable	no	Stamped as an item_metadata row at create-from-template time.
definition_id	string	yes	metadata_definitions.id (UUID).
enum_options	array of string	yes	Allowed values in display order (empty unless field_type = enum).
field_type	string	yes	`string
name	string	yes	The definition’s display name.
required	boolean	yes
slug	string	yes	The definition’s slug.

TemplateSection

A typed section of a template (KAIROS-T-0729). It has the text of a heading in the content, and the type of check on the text under it.

Field	Type	Required	Description
heading	string	yes	The text of the heading, with no #. It matches a heading of each level. One line, not empty, one time in each template.
type	string	yes	free (text that is not empty), plain (text that passes the plain-language check) or ears (each list item fits one frame of EARS). The server refuses each other value.

The server refuses a body with a field that is not in this table (Errors).

TenantCreatedResponse

Response of POST /api/admin/tenants — the T-0008 provisioning report plus the seeded initial admin membership.

Field	Type	Required	Description
boards_created	array of string	yes	Slugs of the default boards created.
initial_admin	TenantInitialAdmin	yes	The organization admin seeded at creation.
metadata_definitions_copied	integer	yes
migrations_applied	array of string	yes	Tenant migration versions applied.
schema	string	yes	The created schema (org_{slug}).
slug	string	yes
templates_copied	integer	yes

TenantDeletedResponse

Response of DELETE /api/admin/tenants/{slug}.

Field	Type	Required	Description
dropped	boolean	yes
slug	string	yes

TenantInitialAdmin

The org-admin membership created with a new tenant.

Field	Type	Required	Description
email	string	yes
external_id	string	yes	OIDC sub.
role	string	yes	Always admin.
user_id	string	yes	public.users.id (UUID).

TenantSummary

A provisioned tenant (GET /api/admin/tenants element).

Field	Type	Required	Description
name	string	yes
schema_exists	boolean	yes	Whether the org_{slug} schema actually exists (drift check).
slug	string	yes

TransitionRequest

Body of POST /api/{family}/{short_code}/transition.

Field	Type	Required	Description
to_column_id	string	yes	Target column (UUID). Must be reachable from the item’s current column per the board’s transition graph, else 422 INVALID_TRANSITION with details.allowed_targets.

The server refuses a body with a field that is not in this table (Errors).

UnclaimedWork

GET /api/teams/{id}/standup/unclaimed response: the last stop of a stand-up.

Field	Type	Required	Description
tasks	array of WorkItem	yes	The tasks on the boards of the team that no one claims, in the state todo or blocked, by short code.

UpdateBoardRequest

Body of PATCH /api/boards/{id} (board settings).

Field	Type	Required	Description
blockers_gate	boolean, nullable	no	The board policy blockers_gate (KAIROS-T-0565), for a delivery board only: true turns it on, false turns it off. On each other level the field is a 422 VALIDATION.
name	string, nullable	no
owner_gate	boolean, nullable	no	The board policy owner_gate (KAIROS-T-0643), for an initiative board only: true turns it on, false turns it off. On each other level the field is a 422 VALIDATION.
parent_gate	boolean, nullable	no	The board policy parent_gate (KAIROS-T-0641), for a delivery board only: true turns it on, false turns it off. On each other level the field is a 422 VALIDATION.
slug	string, nullable	no
team_id	string, nullable	no	The team of the board (UUID, or null for a board of the organization). The team of a board does not change (COLLIERY-T-0243): a value that is not the team of the board is refused with 422 BOARD_TEAM_IS_FIXED. Leave it out, or send the value that the board has.

The server refuses a body with a field that is not in this table (Errors).

UpdateColumnRequest

Body of PATCH /api/boards/{id}/columns/{col_id} — rename, move, and/or set the done flag.

Field	Type	Required	Description
claims	boolean, nullable	no	A task that a person moves into this column gets a claim for the person (KAIROS-T-0359). When the flag goes off, the claims of the tasks in the column end.
is_done	boolean, nullable	no	Mark occupants as completed for children-progress rollups (KAIROS-T-0080). An explicit admin choice — the dead-end heuristic only ever suggests.
keeps_claims	boolean, nullable	no	A task with a claim keeps it in this column, and a task with no claim gets none here (KAIROS-T-0529). When the flag goes off, the claims of the tasks in the column end, unless the column has claims too.
name	string, nullable	no
position	integer, nullable	no	New 0-indexed position; the other columns shift around it.
wip_limit	integer, nullable	no	The WIP limit of the column (KAIROS-T-0371): a number above 0, or null to remove the limit. Leave it out to keep the limit.

The server refuses a body with a field that is not in this table (Errors).

UpdateContentRequest

Body of PATCH /api/{family}/{short_code} — the KAIROS-A-0004 optimistic-concurrency content edit. version is the version the edit is based on; a stale value gets 409 CONFLICT with the current entity in details.current.

Field	Type	Required	Description
content	string	yes	New markdown content (full replacement).
title	string, nullable	no	New title; omitted = keep the current title.
version	integer	yes	The version this edit is based on (“I’m editing version N”).

The server refuses a body with a field that is not in this table (Errors).

UpdateMetadataDefinitionRequest

Body of PATCH /api/metadata-definitions/{id} (org admin). Omitted fields are unchanged; enum_options replaces the full option list (enum definitions only).

Field	Type	Required	Description
entity_types	array, nullable	no	Replacement scope list (KAIROS-T-0078); Some([]) clears the scopes (definition applies to all types again).
enum_options	array, nullable	no	Replacement option list (enum definitions only, non-empty).
name	string, nullable	no
slug	string, nullable	no

The server refuses a body with a field that is not in this table (Errors).

UpdateMetadataRequest

Body of PATCH /api/{entity_type}/{short_code}/metadata: definition slug → value. Values are validated against the definition’s type (KAIROS-A-0003: enum membership, date parse, string passthrough) and upserted; null clears the value. Unknown slugs are 422 VALIDATION.

Field	Type	Required	Description
values	object	yes	Definition slug → new value (null removes the value).

The server refuses a body with a field that is not in this table (Errors).

UpdateNotificationSettingsRequest

PUT /api/me/notification-settings body: the kinds to turn on (true) or off (false). A kind that is not in the body does not change.

Field	Type	Required	Description
agent_key_revoked	boolean, nullable	no
blocked_again	boolean, nullable	no
blocker_cancelled	boolean, nullable	no
blocker_cleared	boolean, nullable	no
cancelled	boolean, nullable	no
claim_dropped	boolean, nullable	no
claim_stale	boolean, nullable	no
delivery_failing	boolean, nullable	no
hand_off	boolean, nullable	no
key_expiring	boolean, nullable	no
mention	boolean, nullable	no
mute_keys	array, nullable	no	Agent keys to mute (ids). A notice from a muted key makes no notification for you (KAIROS-T-0737).
notice	boolean, nullable	no
p0_bug	boolean, nullable	no
proposal_decided	boolean, nullable	no
unmute_keys	array, nullable	no	Agent keys to unmute (ids).
watch	boolean, nullable	no

The server refuses a body with a field that is not in this table (Errors).

UpdateOrgMemberRequest

Body of PATCH /api/members/{user_id} — role change. Demoting the last admin is rejected (422 LAST_ADMIN).

Field	Type	Required	Description
role	string	yes	`admin

The server refuses a body with a field that is not in this table (Errors).

UpdateRepositoryRequest

Body of PATCH /api/repositories/{slug} — every field optional; team re-homes the repository. The tasks that link to it do not change: each stays on its board and keeps its link (COLLIERY-T-0219, COLLIERY-A-0023). A field with the value of the repository changes nothing. The server does not examine the form of that value (COLLIERY-T-0267).

Field	Type	Required	Description
code_index_build	CodeIndexBuild, nullable	no
code_index_summaries	CodeIndexSummaries, nullable	no
default_branch	string, nullable	no	The form is that of default_branch in CreateRepositoryRequest. A value sets the branch by hand (KAIROS-T-0430): the builder indexes it, whatever the forge says.
default_branch_source	DefaultBranchSource, nullable	no
description	string, nullable	no
forge_filters	ForgeFilters, nullable	no
issue_import_interval	string, nullable	no	How often the repository takes its open issues with no webhook (KAIROS-T-0670). Org admin only. off, or a number with a unit: 90s, 15m, 1h, 1d. The shortest interval is 1 minute and the longest is 30 days. The repository needs a read token. The import needs no webhook.
repo_url	string, nullable	no	The form is that of repo_url in CreateRepositoryRequest.
site_enabled	boolean, nullable	no	The site switch (KAIROS-T-0406). Off: a publish is refused, and the site is not served.
slug	string, nullable	no
team	string, nullable	no	New owning team (UUID or slug).

The server refuses a body with a field that is not in this table (Errors).

UpdateStandupGroupRequest

PATCH /api/standup-groups/{id} body: send name, people, or both.

Field	Type	Required	Description
name	string, nullable	no	The new name.
people	array, nullable	no	All the people of the group after the change: the user id (UUID) or the user name of each. A person who is not in the list leaves the group.

The server refuses a body with a field that is not in this table (Errors).

UpdateStreamRequest

Body of PATCH /api/delivery-streams/{id}.

Field	Type	Required	Description
description	string, nullable	no
name	string, nullable	no
slug	string, nullable	no

The server refuses a body with a field that is not in this table (Errors).

UpdateTeamPageRequest

Body of PATCH /api/teams/{id}/pages/{page_id} — EITHER a version-checked content edit (content present, version required) OR a structural rename/move (slug/parent_id/position); mixing both in one call is a 422.

Field	Type	Required	Description
content	string, nullable	no	New markdown content; requires version.
move_to_root	boolean	no	Move the node to the tree root (parent_id ignored when set).
parent_id	string, nullable	no	New parent folder id (move). JSON null cannot distinguish “unchanged” from “move to root” — set move_to_root for the latter.
position	integer, nullable	no	New display position.
slug	string, nullable	no	New sibling slug (rename).
title	string, nullable	no	New title (content edits only).
version	integer, nullable	no	The version this edit is based on (KAIROS-A-0004 pattern; 409 with details.current when stale).

The server refuses a body with a field that is not in this table (Errors).

UpdateTeamRequest

Body of PATCH /api/teams/{id}.

Field	Type	Required	Description
name	string, nullable	no
site_enabled	boolean, nullable	no	The docs site of the team (KAIROS-T-0404): on by default. Off, its rendered pages are not served.
slug	string, nullable	no
team_type	string, nullable	no

The server refuses a body with a field that is not in this table (Errors).

UpdateTemplateRequest

Body of PATCH /api/templates/{id} (org admin). Omitted fields are unchanged; metadata replaces the full association list.

Field	Type	Required	Description
content	string, nullable	no
metadata	array, nullable	no	Replacement metadata association list.
name	string, nullable	no
sections	array, nullable	no	Replacement list of the typed sections (KAIROS-T-0729); [] removes each one. Not sent when None.
slug	string, nullable	no

The server refuses a body with a field that is not in this table (Errors).

UploadedCodeIndex

The answer to PUT /api/repositories/{slug}/code-indexes/{commit}.

Field	Type	Required	Description
index	CodeIndex	yes	The index as Kairos keeps it now.
new_summaries	integer	yes	The summaries of the upload that the pool of the repository did not have.
pool_size	integer	yes	The summaries in the pool of the repository after the upload.

UserBoardGrants

The grants of one person on one board (a row of [UserGrants]).

Field	Type	Required	Description
applicable	array of string	yes	The capabilities that apply at the level of the board. A change can grant only these on the board.
board_id	string	yes	The board (UUID).
board_level	string	yes	`strategy
board_name	string	yes
board_slug	string	yes
capabilities	array of string	yes	The stored grants of the person on the board (sorted). Globs too.

UserGrants

The grants of one person on the boards that the caller administers, and the teams of the person (KAIROS-T-0413). The answer of GET and PATCH /api/members/{user_id}/grants.

Field	Type	Required	Description
boards	array of UserBoardGrants	yes	One row for each live board that the caller administers. The order is by level (strategy, initiative, delivery, ADR), then by name.
display_name	string	yes
email	string	yes
teams	array, nullable	no	The teams of the person, by name. null when the caller cannot change team members.
user_id	string	yes	public.users.id (UUID).

UserTeam

A team of a person (an element of [UserGrants::teams]).

Field	Type	Required	Description
name	string	yes
slug	string	yes
team_id	string	yes	The team (UUID).

VectorProviderSettings

Where the vectors of the code index summaries are made.

Field	Type	Required	Description
base_url	string, nullable	no
model	string, nullable	no
provider	string	yes	embedded (the model in the server) or remote (an OpenAI-compatible embeddings endpoint).
secret	SecretStatus	yes	The API key of the endpoint. A local Ollama needs none.

WatchList

GET /api/me/watches response: each watch of the caller, by code.

Field	Type	Required	Description
items	array of WatchedItem	yes

WatchRequest

PUT /api/items/{short_code}/watch body. A second PUT changes with_children of the watch.

Field	Type	Required	Description
with_children	boolean, nullable	no	true: a change of a child of the item tells you too. Default false.

The server refuses a body with a field that is not in this table (Errors).

WatchState

The watch of the caller on one item (KAIROS-T-0736): GET, PUT and DELETE /api/items/{short_code}/watch.

Field	Type	Required	Description
short_code	string	yes	The code of the item.
watching	boolean	yes	true when the caller watches the item.
with_children	boolean	yes	true when the watch includes the children of the item (its parent edges, one level). false when the caller does not watch.

WatchedItem

One watch of the caller, in GET /api/me/watches.

Field	Type	Required	Description
archived	boolean	yes	true when the item is archived.
board	string, nullable	no	The name of the board of the item; for a document, its owner board (KAIROS-T-0763).
claim	string, nullable	no	The person who claims the task: the display name, else the email.
column	string, nullable	no	The name of the column of the item. A document has no column.
created_at	string	yes	When the caller started the watch (RFC 3339).
entity_type	string	yes	`strategy
short_code	string	yes	The code of the item now.
state	string	no	The state of the item: todo, active, blocked or done (the column of the Watching lane of the “for me” page). Active and Blocked follow the rule of GET /api/me/work; done is a done column; a document is todo.
title	string	yes	The title of the item now.
updated_at	string	no	The last change of the item (RFC 3339).
with_children	boolean	yes	true when the watch includes the children of the item.

WebhookDelivery

One delivery of the log, with its tries.

Field	Type	Required	Description
created_at	string	yes
event	string	yes	task.entered_column, task.unblocked or ping.
finished_at	string, nullable	no
id	string	yes	The id; the value of X-Kairos-Delivery.
last_error	string, nullable	no
log	array of WebhookDeliveryTry	yes	Each try, oldest first.
next_try_at	string, nullable	no
response_code	integer, nullable	no
rule_id	string, nullable	no	The rule that sent it; null for a test delivery.
short_code	string, nullable	no	The code of the task now; null when there is no task.
status	string	yes	`pending
target_id	string	yes
tries	integer	yes

WebhookDeliveryTry

One try of a delivery.

Field	Type	Required	Description
at	string	yes
duration_ms	integer	yes
error	string, nullable	no
ok	boolean	yes	True: the target answered with a 2xx code.
response_code	integer, nullable	no
try_number	integer	yes	1 for the first try.

WebhookTarget

A webhook target of a board: a URL. Kairos sends signed deliveries to it. The secret is never in this type: Kairos shows it one time, in [CreatedWebhookTarget].

Field	Type	Required	Description
board_id	string	yes
consecutive_failures	integer	yes	The failed tries in a row.
created_at	string	yes
created_by	string	yes
disabled_at	string, nullable	no
disabled_reason	string, nullable	no
enabled	boolean	yes	False: Kairos turned the target off after failed tries, and sends nothing to it until a board manager turns it on again. Then Kairos sends the deliveries that it skipped (KAIROS-T-0577).
id	string	yes
name	string	yes
redelivered	integer, nullable	no	Only in the answer of enable and redeliver (KAIROS-T-0577): the number of skipped deliveries that Kairos queued again.
url	string	yes	The URL. A person who cannot configure the board gets it with no query and no fragment.

WorkBlocker

An open blocker of an item of the work.

Field	Type	Required	Description
short_code	string	yes
title	string	yes

WorkBoard

The board of an item of the work.

Field	Type	Required	Description
id	string	yes	Board id (UUID).
name	string	yes
slug	string	yes

WorkItem

One item of the work. No item is in a done column.

Field	Type	Required	Description
blockers	array of WorkBlocker	no	The open blockers: the items, not in a done column, with a blocks edge to this item.
board	WorkBoard	yes	The board of the item.
claim	TaskClaim, nullable	no
column_id	string	yes	The column of the item: id (UUID) and name.
column_name	string	yes
entity_type	string	yes	strategy, initiative or task.
id	string	yes	Entity id (UUID).
owner	ItemOwner, nullable	no
reasons	array of string	yes	Why the item is in the work: owned, claimed, under_my_initiative, blocked_by_my_work, and unclaimed (the last stop of a stand-up).
short_code	string	yes
state	string	yes	todo, active or blocked. Blocked: the item has an open blocker, or it is in a column named Blocked.
title	string	yes