Work items

The five entity families. Every one has the same shape — list, get, create, update, delete — and the same optimistic-concurrency contract on update (KAIROS-A-0004): submit the version you read, and a concurrent edit gets 409 with the current entity in details.current. A write to a claimed task by a different person gets the header Kairos-Warning: <code> claimed by <name> since <time> (KAIROS-T-0359). A task with open blockers can move into a claims column or a done column. That answer gets the header Kairos-Warning: <code> moved into <column>, blocked by <blocker> (open) (KAIROS-T-0565).

strategies

GET /api/strategies

List strategies (open tenant-wide, S-0005 list envelope).

?include_deleted=true widens the listing to archived work, each row marked with archived_at (KAIROS-A-0020 rule 2). Default false: rule 3 is that a listing nobody asked hides put-away work.

Parameter	In	Required	Type	Description
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).
include_deleted	query	no	boolean	Include archived (put-away) rows, each marked with archived_at (KAIROS-A-0020 rule 2). Default false — rule 3 is that a listing nobody asked hides them. total widens with the page, never independently of it.

Response	Body	Meaning
200	ListEnvelope_Strategy	Page of strategies
401	ErrorEnvelope	Missing/invalid token

POST /api/strategies

Create a strategy (requires manage_strategies on the target board).

Parameter	In	Required	Type	Description
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, CreateStrategyRequest

Response	Body	Meaning
201	Strategy	Created
403	ErrorEnvelope	Missing capability
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	Unknown board/column

GET /api/strategies/{short_code}

Get one strategy by short code (open tenant-wide).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Strategy short code

Response	Body	Meaning
200	Strategy	The strategy
404	ErrorEnvelope	Unknown short code

DELETE /api/strategies/{short_code}

Soft-delete a strategy, cascading to its parent descendants (KAIROS-A-0001).

The edit rule applies (COLLIERY-T-0228). The caller created the strategy, holds manage_strategies on its board, or is an organization admin.

The cascade applies the same rule to each descendant (COLLIERY-T-0234). It archives a descendant that the caller can edit. It stops at a descendant that the caller cannot edit, and archives nothing below it. not_reached names each descendant that stays.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Strategy short code

Response	Body	Meaning
200	DeleteResponse	Soft-deleted; notes the cascade
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code

PATCH /api/strategies/{short_code}

Update strategy content (KAIROS-A-0004 optimistic concurrency).

The edit rule applies (COLLIERY-T-0228). The caller created the strategy, holds manage_strategies on its board, or is an organization admin.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Strategy short code

Request body (required): application/json, UpdateContentRequest

Response	Body	Meaning
200	Strategy	Updated (new version)
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	Stale version; details.current carries the current entity

POST /api/strategies/{short_code}/transition

Move a strategy to another column (requires transition_items on the strategy’s board; the move must exist in the board’s transition graph). The creator of the strategy gets no right here (COLLIERY-T-0228).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Strategy short code
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, TransitionRequest

Response	Body	Meaning
200	Strategy	Transitioned (new column)
403	ErrorEnvelope	Missing capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	Invalid transition; details.allowed_targets lists valid moves

initiatives

GET /api/initiatives

List initiatives (open tenant-wide, S-0005 list envelope).

?include_deleted=true widens the listing to archived work, each row marked with archived_at (KAIROS-A-0020 rule 2). Default false: rule 3 is that a listing nobody asked hides put-away work.

Parameter	In	Required	Type	Description
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).
include_deleted	query	no	boolean	Include archived (put-away) rows, each marked with archived_at (KAIROS-A-0020 rule 2). Default false — rule 3 is that a listing nobody asked hides them. total widens with the page, never independently of it.

Response	Body	Meaning
200	ListEnvelope_Initiative	Page of initiatives
401	ErrorEnvelope	Missing/invalid token

POST /api/initiatives

Create an initiative (requires manage_initiatives on the target board). bucket_type set marks it as a bucket (is_bucket derived).

parent (KAIROS-T-0572) is the short code of the parent strategy. Kairos writes the initiative and the edge in one transaction: a refused parent leaves no initiative.

Parameter	In	Required	Type	Description
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, CreateInitiativeRequest

Response	Body	Meaning
201	Initiative	Created
403	ErrorEnvelope	Missing capability
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	Unknown board/column/parent, a column that is not the entry column of the board, a parent that is not a strategy, or bad enum value

GET /api/initiatives/{short_code}

Get one initiative by short code (open tenant-wide).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Initiative short code

Response	Body	Meaning
200	Initiative	The initiative
404	ErrorEnvelope	Unknown short code

DELETE /api/initiatives/{short_code}

Soft-delete an initiative, cascading to its parent descendants (KAIROS-A-0001).

The edit rule applies (COLLIERY-T-0228). The caller created the initiative, holds manage_initiatives on its board, or is an organization admin.

The cascade applies the same rule to each descendant (COLLIERY-T-0234). It archives a descendant that the caller can edit. It stops at a descendant that the caller cannot edit, and archives nothing below it. not_reached names each descendant that stays.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Initiative short code

Response	Body	Meaning
200	DeleteResponse	Soft-deleted; notes the cascade
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code

PATCH /api/initiatives/{short_code}

Update initiative content (KAIROS-A-0004 optimistic concurrency).

The edit rule applies (COLLIERY-T-0228). The caller created the initiative, holds manage_initiatives on its board, or is an organization admin.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Initiative short code

Request body (required): application/json, UpdateContentRequest

Response	Body	Meaning
200	Initiative	Updated (new version)
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	Stale version; details.current carries the current entity

PUT /api/initiatives/{short_code}/complexity

Set the complexity of an initiative, or clear it with none.

The edit rule applies (COLLIERY-T-0228). The caller created the initiative, or is a member of its board. Or the caller holds manage_initiatives on its board, or is an organization admin. The complexity is not content: the change makes no new version and no history row. It writes one activity row and sends item_updated.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Initiative short code

Request body (required): application/json, SetComplexityRequest

Response	Body	Meaning
200	Initiative	Complexity set or cleared
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code
422	ErrorEnvelope	No complexity sent, or a bad value

POST /api/initiatives/{short_code}/transition

Move an initiative to another column (requires transition_items on the initiative’s board). The creator of the initiative gets no right here (COLLIERY-T-0228).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Initiative short code
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, TransitionRequest

Response	Body	Meaning
200	Initiative	Transitioned (new column)
403	ErrorEnvelope	Missing capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	Invalid transition; details.allowed_targets lists valid moves

tasks

GET /api/tasks

List tasks (open tenant-wide, S-0005 list envelope).

?include_deleted=true widens the listing to archived work, each row marked with archived_at (KAIROS-A-0020 rule 2). Default false: rule 3 is that a listing nobody asked hides put-away work.

Parameter	In	Required	Type	Description
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).
include_deleted	query	no	boolean	Include archived (put-away) rows, each marked with archived_at (KAIROS-A-0020 rule 2). Default false — rule 3 is that a listing nobody asked hides them. total widens with the page, never independently of it.

Response	Body	Meaning
200	ListEnvelope_Task	Page of tasks
401	ErrorEnvelope	Missing/invalid token

POST /api/tasks

Create a task. task_type defaults to task.

A task starts in the entry column of its board (KAIROS-T-0566). A column_id of another column gives a 422. Create the task there, then move it. The move runs the claim, the WIP warning and the dispatch rules of the column. The dispatch rules of the entry column fire for the create.

A caller with manage_tasks on the target board can use any work class. Every other member of the tenant sends a request (file_backlog, COLLIERY-T-0218, COLLIERY-A-0023): the target is a delivery board, and the work class is support.

Name the board with board_id, or name a team with team_id to use the delivery board of that team (COLLIERY-T-0217, COLLIERY-A-0023). repository is an optional link. It can be any live repository, and it does not choose the board.

parent (KAIROS-T-0572) is the short code of the parent initiative. Kairos writes the task and the edge in one transaction: a refused parent leaves no task. The link rule applies to the edge; the creator of the task can edit it, so it passes. In a claims column, parent_gate applies (KAIROS-A-0040).

Parameter	In	Required	Type	Description
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, CreateTaskRequest

Response	Body	Meaning
201	Task	Created
403	ErrorEnvelope	Missing capability. For a caller without manage_tasks on the board: the work class planned, or a board that is not a delivery board
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	No board and no team, a team that is not the team of the board, a team without exactly one delivery board, unknown board/column/repository/parent, a column that is not the entry column of the board, a parent that is not an initiative, PARENT_NOT_ACTIVE (a claims column under an inactive parent), or bad enum value

GET /api/tasks/{short_code}

Get one task by short code (open tenant-wide).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Response	Body	Meaning
200	Task	The task
404	ErrorEnvelope	Unknown short code

DELETE /api/tasks/{short_code}

Archive a task (a soft delete, KAIROS-A-0001). A restore brings it back. To delete a task for good, use POST /api/tasks/{short_code}/purge.

The edit rule applies (COLLIERY-T-0228). The caller created the task, holds manage_tasks on its board, or is an organization admin. Intake is a support-lane task in the entry column, and its archive is a “won’t do”. Kairos refuses an agent’s archive of intake with AGENT_TRIAGE_OFF while the board lets a person decide (KAIROS-T-0537).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Response	Body	Meaning
200	DeleteResponse	Archived; notes the cascade. A restore brings the task back
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability, or AGENT_TRIAGE_OFF (an agent’s archive of intake)
404	ErrorEnvelope	Unknown short code

PATCH /api/tasks/{short_code}

Update task content (KAIROS-A-0004 optimistic concurrency).

The edit rule applies (COLLIERY-T-0228). The caller created the task, holds manage_tasks on its board, or is an organization admin.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Request body (required): application/json, UpdateContentRequest

Response	Body	Meaning
200	Task	Updated (new version)
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	Stale version; details.current carries the current entity

POST /api/tasks/{short_code}/cancel

Cancel a task (KAIROS-T-0362): a “won’t do”, with a reason. The task moves to the done column of its board, and it gets the cancel mark with the reason. The transition rules of the board do not apply. You can cancel a task from each column that is not done. A cancel ends the claim of the task.

A move of the task out of the done column removes the mark. The history keeps the reason (the activity row cancel).

Requires transition_items on the board of the task, the capability of a move. The creator of the task gets no right here.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Request body (required): application/json, CancelTaskRequest

Response	Body	Meaning
200	Task	Cancelled: the task is in the done column, with the mark
403	ErrorEnvelope	Missing capability
404	ErrorEnvelope	Unknown short code
422	ErrorEnvelope	VALIDATION (reason is empty; details.field names it), TASK_DONE (the task is in a done column), or NO_DONE_COLUMN (the board has no done column)

POST /api/tasks/{short_code}/claim

Take the claim of a task in Active that has no claim (KAIROS-T-0528). The caller must be a person. The claim names the caller, with the agent key of the request when an agent made it (KAIROS-A-0024).

Requires transition_items on the board of the task (KAIROS-T-0642): the edit rule gives no claim. No body.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Response	Body	Meaning
200	Task	The caller has the claim
403	ErrorEnvelope	The caller does not hold transition_items on the board of the task
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	CLAIMED (a different person has the claim; the details name the holder), or CONFLICT (the caller has it already)
422	ErrorEnvelope	NOT_CLAIMABLE (the task is not in Active), or VALIDATION (the caller is a service account)

POST /api/tasks/{short_code}/hand-off

Give the claim of a task in Active to a person (KAIROS-T-0359, KAIROS-A-0024). to is a user id, an email or a user name of a person of the organization, or me. The task stays in Active, and the person gets the claim. A service account cannot have a claim.

The person must hold transition_items on the board of the task (KAIROS-T-0530). The team of the board gives it, and so do a grant and the organization admin role. Else the answer is 422 VALIDATION on to.

The person who has the claim may hand it off. Any other caller needs transition_items on the board of the task. That capability moves the task into and out of Active. The creator of the task gets no right here.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Request body (required): application/json, HandOffRequest

Response	Body	Meaning
200	Task	The person has the claim
403	ErrorEnvelope	The caller does not have the claim and does not have transition_items
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	The person has the claim already
422	ErrorEnvelope	NOT_CLAIMABLE (the task is not in Active), or VALIDATION (to is not a person of the organization, or does not hold transition_items on the board of the task)

GET /api/tasks/{short_code}/hand-off-targets

The persons who can get the claim of a task (KAIROS-T-0530). Each person holds transition_items on the board of the task. The team of the board gives it, and so do a grant and the organization admin role. The list is in the order of the email. It has no service account.

Each member of the organization can read the list, as with the members of a board (KAIROS-A-0006).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Response	Body	Meaning
200	array of HandOffTarget	The persons who can get the claim
404	ErrorEnvelope	Unknown short code

POST /api/tasks/{short_code}/move

Move a task to another DELIVERY board (KAIROS-I-0012): it lands in the target’s entry column and follows the target’s team. Requires manage_tasks on the current board AND on the target (org admins bypass, as everywhere). The move does not look at the repository of the task, and the task keeps it (COLLIERY-T-0217, COLLIERY-A-0023). The creator of the task gets no right here (COLLIERY-T-0228).

rename: true (COLLIERY-T-3101) also gives the task the next code of the target board, in the same transaction. Kairos retires the old code. Each reference to the old code in the text of the items changes to the new code, one time. A code in a URL or a path does not change. The response has the new code. Without rename, the task keeps its code.

A task in a done column (completed or cancelled) does not move: 422 TASK_DONE (KAIROS-T-0564). Reopen it first (POST /api/tasks/{short_code}/reopen), then move it.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, MoveTaskRequest

Response	Body	Meaning
200	Task	Moved (new board, entry column)
403	ErrorEnvelope	Missing manage_tasks on either board
404	ErrorEnvelope	Unknown short code or board
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	SAME_BOARD

POST /api/tasks/{short_code}/purge

Delete an archived task for good (KAIROS-T-0362). Nothing can bring it back. Archive the task first (DELETE /api/tasks/{short_code}). Kairos refuses a live task with TASK_LIVE (KAIROS-T-0570).

The purge removes these rows of the task:

• the task, its history and its metadata;
• its edges and its edge proposals;
• its forge links, its external references and its embeddings;
• its retired codes and its forge intake row;
• its claim and its cancel mark.

The items at the other end of the edges stay. The activity rows about the task stay. One new row (purge) names the code and the title. A new import of the issue of an intake task makes a task again.

This is a separate route, and not a flag of DELETE. DELETE archives. A purge must not be one query parameter away from an archive.

Requires purge on the board of the task. Team membership does not give it, and manage_tasks is not enough. An organization admin has it. The creator of the task gets no right here.

Intake is a support-lane task in the entry column. Kairos refuses an agent’s purge of intake with AGENT_TRIAGE_OFF while the board lets a person decide (KAIROS-T-0537). Send the current code. The route does not follow a retired code.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code (the current code)

Response	Body	Meaning
200	PurgeTaskResponse	Deleted for good
403	ErrorEnvelope	Missing purge on the board of the task, or AGENT_TRIAGE_OFF (an agent’s purge of intake)
404	ErrorEnvelope	Unknown short code
422	ErrorEnvelope	TASK_LIVE: the task is not archived. Archive it first

POST /api/tasks/{short_code}/release

End the claim of a task in Active (KAIROS-T-0359, KAIROS-A-0024). The task stays in Active with no claim. It is free for anyone: a claim (POST .../claim) or a move to Active takes it.

The person who has the claim may release it. Any other caller needs transition_items on the board of the task. No body.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Response	Body	Meaning
200	Task	The task has no claim
403	ErrorEnvelope	The caller does not have the claim and does not have transition_items
404	ErrorEnvelope	Unknown short code
422	ErrorEnvelope	NOT_CLAIMABLE (the task is not in Active), or NO_CLAIM (the task has no claim)

POST /api/tasks/{short_code}/reopen

Reopen a done task (KAIROS-T-0564): a completed task or a cancelled task. The task moves to the first column of its board that is not done, by position. On a seeded delivery board, that column is Backlog.

The transition rules of the board do not apply. The board policy parent_gate applies to that column, as for a transition. The reopen removes the cancel mark, and the history keeps the reason. The event is item_transitioned. No body.

Requires transition_items on the board of the task, the capability of a move. The creator of the task gets no right here.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Response	Body	Meaning
200	Task	Reopened: the task is in the first column that is not done
403	ErrorEnvelope	Missing capability
404	ErrorEnvelope	Unknown short code
422	ErrorEnvelope	TASK_NOT_DONE (the task is not in a done column), NO_OPEN_COLUMN (each column of the board is done), or PARENT_NOT_ACTIVE (the column holds claims and the initiative is not active)

PUT /api/tasks/{short_code}/repository

Set the repository a task links to, or clear it (KAIROS-T-0104). The link can be any live repository. The board and the team of the task do not change (COLLIERY-T-0217, COLLIERY-A-0023).

The edit rule applies (COLLIERY-T-0228). The caller created the task, holds manage_tasks on its board, or is an organization admin.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Request body (required): application/json, SetTaskRepositoryRequest

Response	Body	Meaning
200	Task	Repository link updated. null or an empty string clears it
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code
422	ErrorEnvelope	Unknown repository

PUT /api/tasks/{short_code}/state

Write the live state of a task (KAIROS-T-0506): branch, last commit, pushed, PR, next step. Each task has one state. The state is not content: no new version of the task. The edit rule applies: the creator of the task, the holder of its claim, or manage_tasks on its board.

The write is a patch (KAIROS-T-0533). A field that you send gets the value. null clears the field. A field that you do not send keeps its value. Send at least one field. expected_updated_at refuses a write over a state that changed since.

A write that changes a field writes one activity row with the names of the fields (KAIROS-T-0557).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Request body (required): application/json, SetTaskStateRequest

Response	Body	Meaning
200	Task	The task, with its state
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the task, has no claim on it, and lacks manage_tasks
404	ErrorEnvelope	Unknown short code, or the task is archived
409	ErrorEnvelope	The state changed after expected_updated_at; details.state is the current state
422	ErrorEnvelope	The body has no field, a bad expected_updated_at, or an unknown field

POST /api/tasks/{short_code}/transition

Move a task to another column (requires transition_items on the task’s board). The creator of the task gets no right here (COLLIERY-T-0228).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, TransitionRequest

Response	Body	Meaning
200	Task	Transitioned (new column)
403	ErrorEnvelope	Missing capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	Invalid transition; details.allowed_targets lists valid moves

POST /api/tasks/{short_code}/work-class

Move a task between the Planned/Support lanes (KAIROS-T-0077; requires transition_items on the task’s board — lane moves are board moves in UX terms, though the rules engine is never consulted). The creator of the task gets no right here (COLLIERY-T-0228).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Task short code

Request body (required): application/json, SetWorkClassRequest

Response	Body	Meaning
200	Task	Lane updated
403	ErrorEnvelope	Missing capability
404	ErrorEnvelope	Unknown short code
422	ErrorEnvelope	Bad work_class value

documents

GET /api/documents

List documents (open tenant-wide, S-0005 list envelope).

?include_deleted=true widens the listing to archived work, each row marked with archived_at (KAIROS-A-0020 rule 2). Default false: rule 3 is that a listing nobody asked hides put-away work. Note this is the deleted_at sense of archived, not the editorial lifecycle value of the same name (KAIROS-T-0078) — a published document can be editorially archived and perfectly live.

?repository= keeps the documents that impact that repository (COLLIERY-T-0269). The value is the slug or the id of a live repository. An unknown repository is a 422 VALIDATION.

Parameter	In	Required	Type	Description
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).
include_deleted	query	no	boolean	Include archived (put-away) rows, each marked with archived_at (KAIROS-A-0020 rule 2). Default false.
repository	query	no	string	Only the items that impact this repository (slug or UUID of a live repository). An unknown repository is a 404 NOT_FOUND.

Response	Body	Meaning
200	ListEnvelope_Document	Page of documents
401	ErrorEnvelope	Missing/invalid token
422	ErrorEnvelope	Unknown repository

POST /api/documents

Create a document. It needs board: the board that owns the document (COLLIERY-T-3109, see the module docs). The code of the document gets the prefix of that board.

The caller needs manage_documents on that board. With parent_short_code, the document also supports that item. With template_id, the template’s content and metadata defaults are stamped (KAIROS-A-0003).

Parameter	In	Required	Type	Description
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, CreateDocumentRequest

Response	Body	Meaning
201	Document	Created. With parent_short_code, the supports edge is written
403	ErrorEnvelope	Missing manage_documents on the board that the document names
404	ErrorEnvelope	Unknown board
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request. DICTIONARY_EXISTS: the template is dictionary, and the board strategy owns a live dictionary already (details.existing names it)
422	ErrorEnvelope	No board (details.field is board), unknown parent, non-workflow parent, or unknown template. DICTIONARY_NOT_ON_STRATEGY: the template is dictionary, and the board is not the board strategy (KAIROS-A-0079)

GET /api/documents/{short_code}

Get one document by short code (open tenant-wide).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Document short code

Response	Body	Meaning
200	Document	The document
404	ErrorEnvelope	Unknown short code

DELETE /api/documents/{short_code}

Soft-delete a document.

The edit rule applies (COLLIERY-T-0228). The caller created the document, holds manage_documents on the board of the document, or is an organization admin. The archive removes no impacts link, and the restore needs no repair (COLLIERY-T-0269).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Document short code

Response	Body	Meaning
200	DeleteResponse	Soft-deleted; notes the cascade
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code

PATCH /api/documents/{short_code}

Update document content (KAIROS-A-0004 optimistic concurrency).

The edit rule applies (COLLIERY-T-0228). The caller created the document, holds manage_documents on the board of the document, or is an organization admin. The board of the document is its owner board (COLLIERY-T-0269).

Parameter	In	Required	Type	Description
short_code	path	yes	string	Document short code

Request body (required): application/json, UpdateContentRequest

Response	Body	Meaning
200	Document	Updated (new version)
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	Stale version; details.current carries the current entity

PATCH /api/documents/{short_code}/board

Change the owner board of a document (COLLIERY-T-0269).

This is a move and not an edit. The caller needs manage_documents on two boards: the board that owns the document now, and the new board. An organization admin needs no capability. The creator of the document gets no right to change its owner.

Each document has an owner board (COLLIERY-T-3109), and you cannot remove it. The server refuses a null or an 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. Not a content edit: no version bump and no history row. The activity log gets one entry with the action update.

rename: true (COLLIERY-T-3101) also gives the document the next code of the new board. Kairos retires the old code. The references to the old code in the text of the items change one time. The server refuses a rename (422 RENAME_NOT_NEEDED) when the board does not change. It also refuses it when the code has the prefix of the new board.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Document short code

Request body (required): application/json, SetDocumentBoardRequest

Response	Body	Meaning
200	Document	The document, with its owner board
403	ErrorEnvelope	Missing manage_documents on the board that owns the document now, or on the new board
404	ErrorEnvelope	Unknown short code, or unknown board
409	ErrorEnvelope	DICTIONARY_EXISTS: the document is a dictionary, and the board strategy owns a live dictionary already (details.existing names it)
422	ErrorEnvelope	VALIDATION: the body has no board, or a null or empty board (details.field is board). RENAME_NOT_NEEDED: a rename with no change of board, or to the prefix of the code. DICTIONARY_NOT_ON_STRATEGY: the document is a dictionary, and the new board is not the board strategy (KAIROS-A-0079)

PATCH /api/documents/{short_code}/lifecycle

Set a document’s editorial lifecycle (KAIROS-T-0078): a free-transition label — draft | review | published | archived.

The edit rule applies (COLLIERY-T-0228). The caller created the document, holds manage_documents on the board of the document, or is an organization admin. The lifecycle is a label and not a column, so this write is an edit and not a move. Not a content edit: no version bump, no history row; activity-logged and announced via the existing item_updated thin event.

Parameter	In	Required	Type	Description
short_code	path	yes	string	Document short code

Request body (required): application/json, SetLifecycleRequest

Response	Body	Meaning
200	Document	Lifecycle updated
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code
422	ErrorEnvelope	Bad lifecycle value

adrs

GET /api/adrs

List ADRs (open tenant-wide, S-0005 list envelope).

?include_deleted=true widens the listing to archived work, each row marked with archived_at (KAIROS-A-0020 rule 2). Default false: rule 3 is that a listing nobody asked hides put-away work.

?repository= keeps the ADRs that impact that repository (COLLIERY-T-0269). The value is the slug or the id of a live repository. An unknown repository is a 422 VALIDATION.

Parameter	In	Required	Type	Description
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).
include_deleted	query	no	boolean	Include archived (put-away) rows, each marked with archived_at (KAIROS-A-0020 rule 2). Default false.
repository	query	no	string	Only the items that impact this repository (slug or UUID of a live repository). An unknown repository is a 404 NOT_FOUND.

Response	Body	Meaning
200	ListEnvelope_Adr	Page of ADRs
401	ErrorEnvelope	Missing/invalid token
422	ErrorEnvelope	Unknown repository

POST /api/adrs

Create an ADR. On a board: requires manage_adrs on that board. Off-board (no board_id): org-admin-only (A-0006 fallback).

parent (KAIROS-T-0591) is the short code of the item that the ADR supports: a strategy, an initiative or a task. The ADR and its supports edge are one transaction: a refused parent leaves no ADR.

Parameter	In	Required	Type	Description
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, CreateAdrRequest

Response	Body	Meaning
201	Adr	Created
403	ErrorEnvelope	Missing capability
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	Unknown board/column/parent, a parent that is not a strategy, an initiative or a task, or bad date

GET /api/adrs/{short_code}

Get one ADR by short code (open tenant-wide).

Parameter	In	Required	Type	Description
short_code	path	yes	string	ADR short code

Response	Body	Meaning
200	Adr	The ADR
404	ErrorEnvelope	Unknown short code

DELETE /api/adrs/{short_code}

Soft-delete an ADR.

The edit rule applies (COLLIERY-T-0228). The caller created the ADR, holds manage_adrs on its board, or is an organization admin. An off-board ADR has no board: its creator or an organization admin.

Parameter	In	Required	Type	Description
short_code	path	yes	string	ADR short code

Response	Body	Meaning
200	DeleteResponse	Soft-deleted; notes the cascade
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code

PATCH /api/adrs/{short_code}

Update ADR content (KAIROS-A-0004 optimistic concurrency).

The edit rule applies (COLLIERY-T-0228). The caller created the ADR, holds manage_adrs on its board, or is an organization admin. An off-board ADR has no board: its creator or an organization admin.

Parameter	In	Required	Type	Description
short_code	path	yes	string	ADR short code

Request body (required): application/json, UpdateContentRequest

Response	Body	Meaning
200	Adr	Updated (new version)
403	ErrorEnvelope	Refused by the edit rule: the caller did not create the item and lacks the capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	Stale version; details.current carries the current entity

POST /api/adrs/{short_code}/transition

Move an ADR to another column of its board (requires transition_items on the ADR’s board). The creator of the ADR gets no right here (COLLIERY-T-0228). An off-board ADR cannot be transitioned: 422 ITEM_NOT_ON_BOARD.

Parameter	In	Required	Type	Description
short_code	path	yes	string	ADR short code
Idempotency-Key	header	no	string, nullable	Optional. A key that you choose for this write: 8 to 128 characters of letters, digits, ‘.’, ‘_’, ‘:’ and ‘-’ (a UUID is a good key). Send it when you may retry the request. For 24 hours, a request with the same key and the same arguments writes nothing and gives the first status and body again, with the header Idempotent-Replayed: true. The same key with other arguments is refused with REQUEST_KEY_REUSED (KAIROS-A-0065).

Request body (required): application/json, TransitionRequest

Response	Body	Meaning
200	Adr	Transitioned (new column)
403	ErrorEnvelope	Missing capability
404	ErrorEnvelope	Unknown short code
409	ErrorEnvelope	REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	Invalid transition (details.allowed_targets) or ITEM_NOT_ON_BOARD