HTTP API

The Kraft server serves its board, and the JSON API behind it, on one port (127.0.0.1:8765 by default). The kraft command and the MCP server are clients of that API. The pages in this section document part of it: see Routes the pages document. /openapi.json lists every HTTP route.

Stable routes

Only two routes are meant for other programs, and only these keep their shape between minor releases. See Versioning and stability. Who may call them is under Who may call.

GET /api/health

curl -s http://127.0.0.1:8765/api/health | jq .status

The answer carries:

intake_off is true when the server started on an intake.yaml that does not load. A trigger left in policy.yaml still fires. It is false when a reload refused the file and the running schedules are kept.

Who may call

The MCP bearer token is a full-access credential. See Security for the whole model, and Remote access to set a password.

Refusals

A Host is not allowed when:

• Kraft is bound to loopback and the request is not addressed to 127.0.0.1, localhost or [::1].
• Kraft is bound off loopback and the request comes from a browser (it sends Sec-Fetch-Site, Origin, Referer or an HTML Accept) whose Host is neither a loopback name nor in allowed_hosts. The CLI, MCP and curl need no entry there.

A browser opening a page (a GET outside /api with an HTML Accept) gets the 403 as a short HTML page instead. The page names the Host it sent and how to allow it. The WebSocket applies the same Host rules.

The schema

FastAPI generates a schema of every HTTP route:

curl -s http://127.0.0.1:8765/openapi.json | jq '.paths | keys'

These three paths need no login. Open /docs or /redoc in a browser to read the API there.

Both pages load their scripts from a public CDN, jsdelivr. Each script is pinned to one exact release, and your browser refuses it unless it matches the hash Kraft ships. Nothing else on either page comes from another site: their policy lets an image load only from Kraft itself or inline, so ReDoc's "Redocly" logo is not fetched.

On a machine without internet access, load /openapi.json into your own OpenAPI viewer.

Routes the pages document

The pages in this section document the board's routes for work items, repos, chains, harnesses, settings, drafts and the server's own state, and the /api/ws/events WebSocket. They do not document every route. /openapi.json lists every HTTP route, but not the WebSocket, which is only described under Events. The pages leave out these groups, which the board uses and a script rarely needs:

• review threads and their comments;
• login and logout, and the browser sessions;
• search, the index rescan, and reading one indexed document;
• worker session logs and permission asks;
• analytics;
• reading and saving the theme, access, notify and intake settings, sending a test notification, saving the library, reading and saving a chain's file, and the checks that run on them;
• reading one harness provider's Settings view, and reading and saving one harness profile's.

A route listed here is written in full: its method and its path with the /api prefix, as in POST /api/work-items. That is how the route appears in /openapi.json and in a request. A route that is in none of the tables below, nor in the stable routes, has no entry.

The pages can change in any release. A script that must keep working calls the stable routes, or the kraft command with --json. Each table below links a route to its entry.

Work items

Gates

Run control

Ending

Budget

Events

Diff and review

Documents

Opening in an editor

Repos

Chains and library

Harnesses and providers

Settings

Server

Config drafts

A work item's draft

In this section

• Filing, reading and changing work items: filing and duplicating an item, reading the board and one item, changing an item, and acting on several at once.
• Gates, run control, ending and retry: deciding a gate, pausing, resuming, skipping and escalating, ending and archiving an item, retrying it, and the routes a worker calls.
• The work item object: the three shapes a work item answers in, its stored columns, and the fields that need an explanation.
• Budget, events, diff and documents: the daily spend total and raising a budget, the dry run of a create, events paging, the diff and review routes, and a work item's documents.
• Repos, chains, harnesses and the server: connecting, changing and disconnecting a repo, chains and library components, harnesses, changes saved but not applied, the update check, and opening an editor.
• Drafts: the routes the Templates and Settings editors use to keep, change, publish and discard a draft and the result each answers, and the policy and intake-check routes.
• Ops for each draft area: every op a draft takes, by area, and a work item's own draft.