HTTP API

Connecting a repo

The routes a script calls to list the connected repos, probe a repository, connect it and disconnect it.

A script that files work needs its repo connected first. These routes list, probe, connect and disconnect repos. Like the other board routes they can change in any release, and kraft repo connect --json is the stable way to do the same. The routes that change a connected repo's settings are in the schema.

RouteWhat it does
GET /api/reposLists the connected repos and workspaces.
POST /api/repos/probeReads a repository and proposes how to connect it.
POST /api/reposConnects a repository.
DELETE /api/repos?path=Disconnects a repository.

GET /api/repos

Answers the connected repos and workspaces, and the checkout the server was started in when it isn't connected yet.

curl -s http://127.0.0.1:8765/api/repos | jq '.repos[].path'
FieldTypeMeaning
reposlistOne entry per connected repo, as repos.yaml holds it, defaults included.
workspacesobjectThe workspaces: section, by workspace ID.
suggestedstring or nullThe git checkout the server was started in, when it isn't connected yet.

POST /api/repos/probe

Reads a repository and changes nothing. The answer is the proposal that connecting would save.

FieldTypeDefaultMeaning
pathstringrequiredThe absolute path of the repository.
detectbooleantrueWith false the route answers only what needs no detector table: the resolved path, name, branch, submodules, beads and forge.
test_commandstringnoneThe root's test command, in place of the proposed one. "" declares that the repo has no tests.
forgestringnonegithub or gitlab: the forge you already know for a host that names none, so the answer doesn't ask. Added in 2.5

How connect proposes commands says how a proposal is made and what limits the probe. The probe runs in a process of its own with a two-minute limit.

StatusWhen
400The path isn't a git repository, detectors.yaml doesn't load, or the probe ran past two minutes.
422path is relative.
429Two probes are already running. Try again shortly.

POST /api/repos

Connects a repository: it probes it, saves the entry to repos.yaml, and indexes the repo for search. It answers 201 with the saved entry and the probe's proposal.

curl -s -X POST http://127.0.0.1:8765/api/repos \
  -H 'Content-Type: application/json' \
  -d '{"path": "/home/me/src/app", "test_command": "pytest -q"}'
FieldTypeDefaultMeaning
pathstringrequiredThe absolute path of the repository.
namestringthe directory nameThe repo's name.
default_chainstringdefaultThe chain its items run when none is named.
test_commandstringthe probe's proposalThe root's test command. "" declares a repo with no tests.
setup_commandstringthe probe's proposalThe command that prepares a worktree. "" declares none.
enabledbooleantrue with a test command or test scopes, else falseWhether auto-intake and an agent may file work on the repo. A person can file on a disabled repo by hand.
forge_accountstringnoneThe forge account the repo uses. Added in 2.5

The body also takes test_scopes, forge, project, models, deny_tools and steering, the fields of the same names in repos.yaml.

Commands an agent gives are held for a person. When the request comes from a worker session or the MCP server and gives a test_command, a non-empty setup_command or test_scopes, the repo is saved disabled, whatever enabled says, and the answer carries held.

StatusWhen
400The path isn't a git repository, or the probe fails and the body doesn't give both commands.
403forge_account from a worker session or the MCP server: a repo's account is a person's choice. Added in 2.5
409The repo is already connected.
422The path is relative, the repository has no commit yet, enabled: true has no test command or scopes, forge_account names no account, or repos.yaml wouldn't load with the entry. detail says which.

DELETE /api/repos?path=

Disconnects the repo at path: it removes the entry from repos.yaml and from the search index. No file of the repository is touched and no work item is dropped. kraft repo disconnect calls it. It answers 204 with no body.

StatusWhen
404path isn't a connected repo, or is relative.
409The repo has open items, paused ones included. The answer gives the count: complete, cancel or abandon them first.
409The repo's add-on library is still named by configuration, or an add-on is busy. The answer names where.
422A workspace in repos.yaml still names the repo.
Copyright © 2026