The deployment itself

Activity, administration, and what the deployment reports about itself.

activity

GET /api/activity

Query the activity log with combinable filters + pagination.

An entry about an item has entity_short_code, entity_title and entity_archived_at (COLLIERY-T-0262). The three fields are null for an entry that is not about an item. They are null too for an item that Kairos does not have.

team is the slug or the id of a live team (COLLIERY-T-0265). An entry passes the filter when its actor is a member of the team at the time of the request. The entity of the entry does not change the result. The server applies each filter before the page, so total is the count after the filters. An unknown team is a 422 VALIDATION.

total is exact up to 1000 entries (KAIROS-T-0627). When the page ends after entry 1000, the bound is the end of the page. Past the bound the count stops: total is the bound + 1. That means “more than the bound”.

Parameter	In	Required	Type	Description
entity_id	query	no	string	Filter: activity for a specific entity (UUID).
actor_id	query	no	string	Filter: activity by a specific user (UUID).
action	query	no	string	Filter: activity by action type.
since	query	no	string	Filter: activity at or after this RFC 3339 timestamp.
team	query	no	string	Filter: activity by the members of a team (COLLIERY-T-0265). The value is the slug or the id (UUID) of a live team. An entry passes when its actor is a member of the team at the time of the request.
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).

Response	Body	Meaning
200	ListEnvelope_ActivityEntry	Page of activity entries, newest first
422	ErrorEnvelope	Malformed filter value

admin

GET /api/admin/tenants

List provisioned tenants. Deployment-admin only.

Parameter	In	Required	Type	Description
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).

Response	Body	Meaning
200	ListEnvelope_TenantSummary	Page of tenants
401	ErrorEnvelope	Missing/invalid token
403	ErrorEnvelope	Caller is not a deployment admin

POST /api/admin/tenants

Create a tenant: T-0008 provisioning (org row, schema, migrations, defaults, boards) PLUS the initial org-admin membership, in one transaction. Deployment-admin only.

Request body (required): application/json, CreateTenantRequest

Response	Body	Meaning
201	TenantCreatedResponse	Provisioned; initial_admin reports the seeded org admin
401	ErrorEnvelope	Missing/invalid token
403	ErrorEnvelope	Caller is not a deployment admin
409	ErrorEnvelope	Tenant already exists
422	ErrorEnvelope	Invalid slug, or the initial admin has never logged in

DELETE /api/admin/tenants/{slug}

Drop a tenant: removes the org_{slug} schema (CASCADE) and the organization row. Destructive and unrecoverable — requires ?confirm=true (422 CONFIRMATION_REQUIRED otherwise). Deployment-admin only.

Parameter	In	Required	Type	Description
slug	path	yes	string	Tenant slug
confirm	query	no	boolean	Must be true to actually drop the tenant.

Response	Body	Meaning
200	TenantDeletedResponse	Dropped
401	ErrorEnvelope	Missing/invalid token
403	ErrorEnvelope	Caller is not a deployment admin
404	ErrorEnvelope	Unknown tenant
422	ErrorEnvelope	CONFIRMATION_REQUIRED (missing ?confirm=true)

meta

POST /api/auth/token

Doc-stub for POST /api/auth/token (KAIROS-T-0039): the handler lives in [crate::web]. PUBLIC (pre-login by nature): the same-origin relay to the issuer’s token endpoint for the SPA’s PKCE code exchange and refresh grant (IdP token endpoints rarely serve CORS).

Request body: application/x-www-form-urlencoded, —

Response	Body	Meaning
200	—	The issuer’s token response, passed through
400	—	The issuer rejected the grant (OAuth error JSON, passed through)
422	ErrorEnvelope	Unsupported grant_type or missing field
502	ErrorEnvelope	The configured issuer is unreachable

GET /api/config

Doc-stub for GET /api/config (KAIROS-T-0039): the handler lives in [crate::web]. PUBLIC (no auth): it is the SPA’s discovery endpoint — exactly the information a login page needs before any token exists.

Response	Body	Meaning
200	—	SPA login configuration (public): {issuer, client_id, authorization_endpoint, scope, api_bearer} — the deployment issuer, the GUI’s OAuth client id (KAIROS_WEB_CLIENT_ID), the issuer’s authorization endpoint from OIDC discovery, the scope to request at login (offline_access only when the issuer’s scopes_supported does not leave it out), and which token the SPA sends as the /api bearer (access_token default, or id_token for opaque-access-token issuers like Google Workspace, KAIROS-T-0054)
502	ErrorEnvelope	The configured issuer is unreachable

GET /api/openapi.json

Serve the aggregated spec.

Response	Body	Meaning
200	—	This OpenAPI 3.x document (application/json)
401	ErrorEnvelope	Missing/invalid token
403	ErrorEnvelope	Not a member of the organization

GET /api/whoami

Doc-stub for GET /api/whoami: the handler lives in [crate::app] (T-0017’s middleware probe), outside the api tree, and its response types predate the shared DTO crate — so the spec documents the route here without a response schema. Never called; it exists only for the #[utoipa::path] expansion referenced by [ApiDoc].

Response	Body	Meaning
200	—	The authenticated user, the resolved organization and the caller’s role in it, the caller’s teams, and the caller’s board-scoped capability grants (KAIROS-A-0006, grouped by board) (crate::app::WhoamiResponse: {user: {id, external_id, email, display_name}, organization: {id, slug, role}, teams: [{id, slug, name}], capabilities: [{board_id, board_slug, grants: [..]}], structure: [{scope, board_id, board_slug}]}). structure lists the grants of manage_structure (KAIROS-T-0337): scope organization or board. agent_key is {id, scope} when the request uses an agent key (KAIROS-T-0536), else null. scope null: the key has no scope and no limit.
401	ErrorEnvelope	Missing/invalid token
403	ErrorEnvelope	Not a member of the organization