Tenant configuration

Org-admin surfaces: the metadata and template definitions that shape what work items can carry.

metadata-definitions

GET /api/metadata-definitions

List metadata definitions with their enum options and scopes (open tenant-wide), optionally filtered to one entity type’s catalog.

Parameter	In	Required	Type	Description
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).
entity_type	query	no	string	Only definitions applying to this entity type (`strategy

Response	Body	Meaning
200	ListEnvelope_MetadataDefinition	Page of definitions
422	ErrorEnvelope	Bad entity_type value

POST /api/metadata-definitions

Create a metadata definition (org admin only, A-0006).

Request body (required): application/json, CreateMetadataDefinitionRequest

Response	Body	Meaning
201	MetadataDefinition	Created
403	ErrorEnvelope	Caller is not an org admin
422	ErrorEnvelope	Bad field_type, option rules, or duplicate slug

GET /api/metadata-definitions/{id}

Get one definition with its enum options (open tenant-wide).

Parameter	In	Required	Type	Description
id	path	yes	string	The slug or the id (UUID) of the definition

Response	Body	Meaning
200	MetadataDefinition	The definition
404	ErrorEnvelope	Unknown slug or id

DELETE /api/metadata-definitions/{id}

Delete a definition (org admin only). Refused with 409 DEFINITION_IN_USE while any item value or template association references it (S-0005 “fails if in use”) — and the refusal names the carrying work and templates, archived carriers marked (KAIROS-T-0162).

Parameter	In	Required	Type	Description
id	path	yes	string	The slug or the id (UUID) of the definition

Response	Body	Meaning
200	DeletedResponse	Deleted
403	ErrorEnvelope	Caller is not an org admin
404	ErrorEnvelope	Unknown slug or id
409	ErrorEnvelope	Definition is in use; the message names the carrying items and templates

PATCH /api/metadata-definitions/{id}

Update a definition (org admin only): rename, re-slug, and/or replace the enum option list. The field type is immutable — existing item_metadata values were validated against it (A-0003).

A body with no field is a 422 VALIDATION. A body whose values are equal to the stored values writes nothing and makes no activity entry. A real change makes an activity entry (KAIROS-T-0268).

Parameter	In	Required	Type	Description
id	path	yes	string	The slug or the id (UUID) of the definition

Request body (required): application/json, UpdateMetadataDefinitionRequest

Response	Body	Meaning
200	MetadataDefinition	Updated
403	ErrorEnvelope	Caller is not an org admin
404	ErrorEnvelope	Unknown slug or id
422	ErrorEnvelope	No field to change, option rules, or duplicate slug

templates

GET /api/templates

List templates (open tenant-wide).

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_Template	Page of templates

POST /api/templates

Create a template (org admin only, A-0006). Metadata entries reference existing definitions by slug; defaults are validated against the definition’s type (A-0003).

Request body (required): application/json, CreateTemplateRequest

Response	Body	Meaning
201	TemplateDetail	Created
403	ErrorEnvelope	Caller is not an org admin
422	ErrorEnvelope	Unknown definition slug, invalid default, duplicate slug, or an unknown section type or bad heading

GET /api/templates/{id}

Get one template: content plus its associated metadata definitions with defaults/required flags (open tenant-wide).

Parameter	In	Required	Type	Description
id	path	yes	string	The slug or the id (UUID) of the template

Response	Body	Meaning
200	TemplateDetail	The template with its metadata fields
404	ErrorEnvelope	Unknown slug or id

DELETE /api/templates/{id}

Delete a template (org admin only). Hard delete: associations cascade and existing documents keep their content (documents.template_id is set NULL by the DDL).

Parameter	In	Required	Type	Description
id	path	yes	string	The slug or the id (UUID) of the template

Response	Body	Meaning
200	DeletedResponse	Deleted
403	ErrorEnvelope	Caller is not an org admin
404	ErrorEnvelope	Unknown slug or id

PATCH /api/templates/{id}

Update a template (org admin only): omitted fields are unchanged; metadata replaces the full association list. Existing documents are unaffected (A-0003: no ongoing relationship after stamping).

A body with no field is a 422 VALIDATION. A body whose values are equal to the stored values writes nothing and makes no activity entry. A real change makes an activity entry (KAIROS-T-0268).

Parameter	In	Required	Type	Description
id	path	yes	string	The slug or the id (UUID) of the template

Request body (required): application/json, UpdateTemplateRequest

Response	Body	Meaning
200	TemplateDetail	Updated
403	ErrorEnvelope	Caller is not an org admin
404	ErrorEnvelope	Unknown slug or id
422	ErrorEnvelope	No field to change, unknown definition slug, invalid default, duplicate slug, or an unknown section type or bad heading

organization

GET /api/admin/jobs

The job queue of the organization and of the deployment.

Response	Body	Meaning
200	JobQueueStatus	The jobs by kind and state, and the last failures
403	ErrorEnvelope	The caller is not an organization admin

GET /api/org/code-index-settings

The provider settings of the code index of the tenant. The secrets are a status, never the value.

Response	Body	Meaning
200	CodeIndexSettings	The settings

PUT /api/org/code-index-settings

Set the provider settings of the code index of the tenant (an organization admin). The answer has each secret as a status.

Request body (required): application/json, PutCodeIndexSettings

Response	Body	Meaning
200	CodeIndexSettings	The settings as Kairos keeps them now
403	ErrorEnvelope	Not an organization admin
409	ErrorEnvelope	The version is not the stored version: the settings changed after the read; details.current has them
422	ErrorEnvelope	An unknown provider or field, a value that a provider needs and the body does not give, or a value that is not correct
501	ErrorEnvelope	A secret was sent, and this deployment has no KAIROS_SECRETS_KEY

GET /api/org/dictionary

The dictionary of the organization: its code, its terms and its bad rows. With no dictionary, the code is null and the lists are empty.

Response	Body	Meaning
200	OrganizationDictionary	The dictionary of the organization, the terms sorted by the word

GET /api/org/read-tokens

The read tokens of the organization: the host, who set the token and when (an organization admin). Never the token.

Response	Body	Meaning
200	array of OrgReadToken	The token of each host, as a status
403	ErrorEnvelope	Not an organization admin

PUT /api/org/read-tokens/{host}

Set or replace the read token of the organization for a forge host (an organization admin). Kairos encrypts the token. The builder uses it for each repository on the host, before the token of the repository.

Parameter	In	Required	Type	Description
host	path	yes	string	The forge host, for example github.com

Request body (required): application/json, SetOrgReadTokenRequest

Response	Body	Meaning
200	OrgReadToken	The token is set
403	ErrorEnvelope	Not an organization admin
422	ErrorEnvelope	An unknown field, a host that is not a host, or a token that is empty, too long or has a space
501	ErrorEnvelope	This deployment has no KAIROS_SECRETS_KEY

DELETE /api/org/read-tokens/{host}

Remove the read token of the organization for a forge host (an organization admin). The next fetch of a repository on the host uses the token of the repository, or no token. The answer is the list that stays.

Parameter	In	Required	Type	Description
host	path	yes	string	The forge host, for example github.com

Response	Body	Meaning
200	array of OrgReadToken	The token is removed; the tokens that stay
403	ErrorEnvelope	Not an organization admin
404	ErrorEnvelope	The host has no token
422	ErrorEnvelope	A host that is not a host

GET /api/org/retention

The retention settings of the deployment and the last pass.

Response	Body	Meaning
200	RetentionStatus	The retention settings and the last pass
403	ErrorEnvelope	The caller is not an organization admin