Execution scope

Repositories as first-class execution scope (KAIROS-A-0019) and the git forges behind them.

repositories

POST /api/code-index/query-vector

The vector of the text of a code search, made by the model of the vectors of the index. Each member of the organization can call it.

Request body (required): application/json, QueryVectorRequest

Response	Body	Meaning
200	QueryVector	The vector of the text
422	ErrorEnvelope	The organization has no provider for the model (NO_QUERY_PROVIDER), or the model or the text is not correct (VALIDATION)
502	ErrorEnvelope	The provider did not give the vector (QUERY_VECTOR_FAILED)

GET /api/repositories

The repository directory (open tenant-wide), by slug. ?team= narrows to one owning team.

The response is a page, {items, total, limit, offset}, as for each other list (KAIROS-T-0268). Until 0.11 it was an array of each repository.

Parameter	In	Required	Type	Description
team	query	no	string	Only this team’s repositories (UUID or slug).
forge	query	no	string	With name: the ONE repository registered under this forge (`github
name	query	no	string	owner/repo, paired with forge.
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).

Response	Body	Meaning
200	ListEnvelope_Repository	Page of repositories, by slug
422	ErrorEnvelope	Unknown team

POST /api/repositories

Register a repository under its owning team (org admin, or a manage_tasks holder on that team’s delivery board — self-serve for the team and its agents).

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, CreateRepositoryRequest

Response	Body	Meaning
201	Repository	Registered
403	ErrorEnvelope	Neither org admin nor the owning team
409	ErrorEnvelope	Slug or (forge, name) already registered; or REQUEST_KEY_REUSED: the Idempotency-Key was used for a different request
422	ErrorEnvelope	Bad slug/forge, unknown team, or a field that does not have its form

GET /api/repositories/{slug}

One repository (open tenant-wide): the directory row plus its webhook connection id and in-flight links — everything an agent reads before working in, or filing against, a codebase.

impacted_by has the documents and the ADRs that impact the repository (COLLIERY-T-0269): its vision, its architecture, the decisions about it. It has the live items only. ?include_deleted=true adds the archived items, each marked with archived_at.

owner_team_adrs has the other ADRs of the owner team (KAIROS-T-0599). No impacts link names them. The newest come first, 50 at most. A superseded ADR is not there. owner_team_adrs_total counts them all.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)
include_deleted	query	no	boolean	Include the archived documents and ADRs in impacted_by and owner_team_adrs, each marked with archived_at. Default false.

Response	Body	Meaning
200	RepositoryDetail	The repository
404	ErrorEnvelope	Unknown repository

DELETE /api/repositories/{slug}

Remove a repository (org admin, or manage_structure at the organization, KAIROS-T-0337). Refused with 409 while live tasks or a live webhook connection still reference it.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
200	OrgDeleteResponse	Removed
403	ErrorEnvelope	Not an org admin
404	ErrorEnvelope	Unknown repository
409	ErrorEnvelope	Still referenced by tasks or a connection

PATCH /api/repositories/{slug}

Edit a repository (same gate as create, evaluated against the CURRENT owner). Re-homing to another team does not touch the tasks that link to the repository.

A body can have only the values that the repository has. That request gets 200 with the repository, and the server writes nothing (COLLIERY-T-0267).

To stop the code index builds of the repository, send {"code_index_build": "off"} (KAIROS-T-0398). Kairos cancels the build jobs of the repository that wait for a server, and their runs end as failed. The builder adds no new job. Kairos does not stop a build that runs now, but the build gets no further try. Send "on" to start the builds again. The MCP tool update_repository does the same.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Request body (required): application/json, UpdateRepositoryRequest

Response	Body	Meaning
200	Repository	Updated
403	ErrorEnvelope	Neither org admin nor the owning team
404	ErrorEnvelope	Unknown repository
409	ErrorEnvelope	Slug already taken
422	ErrorEnvelope	Bad slug, unknown team, or a field that does not have its form

GET /api/repositories/{slug}/code-indexes

Each indexed commit of a repository, newest write first.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
200	array of CodeIndex	The indexed commits
404	ErrorEnvelope	Unknown repository

GET /api/repositories/{slug}/code-indexes/builds

The runs of the code index builder for a repository, newest first (KAIROS-T-0331). The server keeps limit in the range 1 to 100, as it does for each list (COLLIERY-T-0264). With no limit, it gives 20. offset skips the newest runs: the pages (KAIROS-T-0584). total is exact.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)
limit	query	no	integer	The most runs in the answer: 20 when not given, 100 at most.
offset	query	no	integer	The runs to skip before the page, newest first: 0 when not given (KAIROS-T-0584).

Response	Body	Meaning
200	CodeIndexBuildList	The runs, newest first
404	ErrorEnvelope	Unknown repository

GET /api/repositories/{slug}/code-indexes/commits

One page of the indexed commits of a repository, newest write first (KAIROS-T-0518). The server keeps limit in the range 1 to 200. The default limit is 50. offset skips the newest rows. total is exact. Each row has the schema version of its index file.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)
limit	query	no	integer	Page size (default 50, max 200).
offset	query	no	integer	Rows to skip (default 0).

Response	Body	Meaning
200	ListEnvelope_CodeIndex	A page of the indexed commits, newest first
404	ErrorEnvelope	Unknown repository

GET /api/repositories/{slug}/code-indexes/nearest

The nearest indexed commit at or below a commit, from the bare clone of the repository. The clone fetches first when it does not have the commit.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)
commit	query	yes	string	The commit to start from (a full commit id).

Response	Body	Meaning
200	NearestCodeIndex	The nearest indexed commit
404	ErrorEnvelope	Unknown repository or commit, or no indexed commit below it
422	ErrorEnvelope	Bad commit
501	ErrorEnvelope	This deployment keeps no clones (KAIROS_CODE_INDEX_DIR)
502	ErrorEnvelope	The fetch from the repository failed

POST /api/repositories/{slug}/code-indexes/rebuild

Ask the builder for a full build of the code index of a repository (KAIROS-T-0332). The body is empty. The answer is 202 with the run. The request resets the breaker of the code index builder of the repository (code_index_breaker, KAIROS-T-0399).

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
202	CodeIndexBuild	The run, as running
403	ErrorEnvelope	No right to change the repository
404	ErrorEnvelope	Unknown repository
409	ErrorEnvelope	A run of the repository is active (CODE_INDEX_BUILD_RUNNING)
422	ErrorEnvelope	The repository has the builder off (CODE_INDEX_BUILD_OFF), or the request has a body
503	ErrorEnvelope	The deployment has no builder (CODE_INDEX_BUILDER_OFF)

GET /api/repositories/{slug}/code-indexes/{commit}

The index file of a commit, with the summaries that its structure uses.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)
commit	path	yes	string	The full commit id

Response	Body	Meaning
200	IndexFile	A kairos-index SQLite file
404	ErrorEnvelope	Unknown repository, or no index of the commit
422	ErrorEnvelope	Bad commit

PUT /api/repositories/{slug}/code-indexes/{commit}

Send the index file of a commit. Kairos adds its summaries to the pool of the repository and keeps its structure for the commit. A commit that has an index gets the new one.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)
commit	path	yes	string	The full commit id
ref	query	no	string	The branch, the pull request or the tag that the index is for, for example main, pull/12 or v1.0.0.

Request body (required): application/vnd.sqlite3, IndexFile

Response	Body	Meaning
200	UploadedCodeIndex	Stored; it replaces the index of the commit
201	UploadedCodeIndex	Stored; the commit had no index
403	ErrorEnvelope	No right to change the repository
404	ErrorEnvelope	Unknown repository
409	ErrorEnvelope	The vectors are of another model than the pool of the repository
413	—	The file is larger than 256 MiB
422	ErrorEnvelope	Bad commit or ref, or a body that is not an index file

GET /api/repositories/{slug}/credential

The status of the read token of a repository. It never has the token.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
200	RepositoryCredential	The status of the token
404	ErrorEnvelope	Unknown repository

PUT /api/repositories/{slug}/credential

Set or replace the read token of a repository (an organization admin, or a member of the owner team). Kairos encrypts the token. The response is the status, with no token.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Request body (required): application/json, SetRepositoryCredentialRequest

Response	Body	Meaning
200	RepositoryCredential	The token is set
403	ErrorEnvelope	Not an organization admin, and not a member of the owner team
404	ErrorEnvelope	Unknown repository
422	ErrorEnvelope	An unknown field, or a token that is empty, too long or has a space
501	ErrorEnvelope	This deployment has no KAIROS_SECRETS_KEY

DELETE /api/repositories/{slug}/credential

Remove the read token of a repository (an organization admin, or a member of the owner team). The next fetch has no credential.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
200	RepositoryCredential	The token is removed
403	ErrorEnvelope	Not an organization admin, and not a member of the owner team
404	ErrorEnvelope	Unknown repository, or the repository has no token

POST /api/repositories/{slug}/credential/check

Test the read token: git ls-remote of the URL of the repository with the token. The result is kept, and the response has it. A failed check is a 200 with last_check_ok: false and the error of git, with the token removed.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
200	RepositoryCredential	The check ran. last_check_ok has the result
403	ErrorEnvelope	Not an organization admin, and not a member of the owner team
404	ErrorEnvelope	Unknown repository, or the repository has no token
409	ErrorEnvelope	The stored token does not decrypt with the key of the deployment

GET /api/repositories/{slug}/import-issues

The last import of the open issues of a repository (KAIROS-T-0487).

Organization admin only. The answer gives the state of the import and its counts. It also gives the interval of the repository and its sync state (KAIROS-T-0670). The sync state has the last complete run, the next run and the count of the record. It also has the counts of the last run and the last error. A repository with an interval answers before its first job, with the state idle.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
200	IssueImport	The last import
403	ErrorEnvelope	Not an org admin
404	ErrorEnvelope	Unknown repository, or no import ran

POST /api/repositories/{slug}/import-issues

Start the import of the open issues of a repository (KAIROS-T-0483).

Organization admin only. The import is a job of the job queue (KAIROS-T-0487).

Each open issue goes through the path of an opened-issue event. The forge filter decides. Then Kairos makes one support task for each issue id on the delivery board of the team. The import skips an issue that a webhook or an earlier import took.

The repository needs a read token with Issues: read (GitHub) or read_api (GitLab). It needs no webhook connection.

The answer is the job, at once. While an import of the repository waits or runs, the answer is that import: one runs at a time. Read the counts with GET /api/repositories/{slug}/import-issues.

The interval of the repository (issue_import_interval, KAIROS-T-0670) runs the same import on a cadence.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
202	IssueImport	The import job: a new one, or the one that waits or runs
403	ErrorEnvelope	Not an org admin
404	ErrorEnvelope	Unknown repository
422	ErrorEnvelope	The repository has no read token, or the forge other

PUT /api/repositories/{slug}/site

Publish the built site of a repository: one .tar.gz of the build folder, with index.html at its root.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)
Content-MD5	header	no	string, nullable	MD5 of the body, base64. When sent, it must match

Request body (required): application/gzip, SiteArchive

Response	Body	Meaning
201	SitePublish	Published; it is the live site now
403	ErrorEnvelope	No capability pages on the delivery board of the owner team
404	ErrorEnvelope	Unknown repository
409	ErrorEnvelope	The site of the repository is off (SITE_OFF)
413	ErrorEnvelope	The archive is larger than the limit (TOO_LARGE)
422	ErrorEnvelope	The archive is refused (ARCHIVE_REFUSED), or Content-MD5 does not match (MD5_MISMATCH)
501	ErrorEnvelope	The deployment has no site store (NO_SITE_STORE)

DELETE /api/repositories/{slug}/site

Unpublish the site of a repository. Its files are deleted from the store; the history stays.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
204	—	Unpublished
403	ErrorEnvelope	No capability pages, and no right to change the repository
404	ErrorEnvelope	Unknown repository, or no published site

GET /api/repositories/{slug}/write-token

The status of the GitHub write-back of a repository. It never has the token.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
200	RepositoryWriteBack	The status of the write-back
404	ErrorEnvelope	Unknown repository

PUT /api/repositories/{slug}/write-token

Set or replace the write token of a GitHub or GitLab repository. An organization admin or a member of the owner team can do it. Kairos encrypts the token. Then Kairos writes each open pull request that links to an item, and each issue whose task changed. The response is the status, with no token.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Request body (required): application/json, SetRepositoryCredentialRequest

Response	Body	Meaning
200	RepositoryWriteBack	The token is set
403	ErrorEnvelope	Not an organization admin, and not a member of the owner team
404	ErrorEnvelope	Unknown repository
422	ErrorEnvelope	Not a GitHub or GitLab repository, an unknown field, or a token that is empty, too long or has a space
501	ErrorEnvelope	This deployment has no KAIROS_SECRETS_KEY

DELETE /api/repositories/{slug}/write-token

Remove the write token of a repository (an organization admin, or a member of the owner team). Kairos writes nothing more to its pull requests.

Parameter	In	Required	Type	Description
slug	path	yes	string	Repository slug (or UUID)

Response	Body	Meaning
200	RepositoryWriteBack	The token is removed
403	ErrorEnvelope	Not an organization admin, and not a member of the owner team
404	ErrorEnvelope	Unknown repository, or the repository has no write token

forge

GET /api/forge-connections

Every live connection (open tenant-wide; secrets never included).

Response	Body	Meaning
200	array of ForgeConnection	Live connections, newest first

POST /api/forge-connections

Connect webhooks for a registered repository (org admin). Returns the delivery URL and the secret — the only time the secret is ever shown. The repository’s forge is the webhook dialect; other repos cannot be connected.

Request body (required): application/json, CreateForgeConnectionRequest

Response	Body	Meaning
201	CreatedForgeConnection	Connected; webhook_secret is shown once
403	ErrorEnvelope	Not an org admin
404	ErrorEnvelope	Unknown repository
409	ErrorEnvelope	Repository already connected
422	ErrorEnvelope	Repository has no webhook-capable forge
501	ErrorEnvelope	Deployment not configured for webhooks

GET /api/forge-connections/{id}

One live connection (open tenant-wide).

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

Response	Body	Meaning
200	ForgeConnection	The connection
404	ErrorEnvelope	Unknown connection

DELETE /api/forge-connections/{id}

Disconnect a repository (soft delete; its links stop being reachable).

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

Response	Body	Meaning
200	OrgDeleteResponse	Disconnected
403	ErrorEnvelope	Not an org admin
404	ErrorEnvelope	Unknown connection

POST /api/forge-connections/{id}/rotate

Rotate a connection’s secret. Because the secret is DERIVED from the connection id, rotation mints a new connection (same repo, new id) and disconnects the old one — so the delivery URL changes too and the operator updates both fields in the forge.

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

Response	Body	Meaning
200	CreatedForgeConnection	Rotated; new URL and secret shown once
403	ErrorEnvelope	Not an org admin
404	ErrorEnvelope	Unknown connection
501	ErrorEnvelope	Deployment not configured for webhooks