Board API

folio-board-server api serves one versioned HTTP API, locally on loopback or behind HTTPS. The live kanban calls it; so can a script. Local Git, hosted GitHub and SQLite guides cover the setup.

curl -s http://127.0.0.1:4350/v1/health \
  -H "Authorization: Bearer $TOKEN"

{"store":"local","location":"/home/ana/widgets/board","read_only":false,"actor":"ana","rev":"6ade54d…"}

A hosted server also names the board’s source, its repository and branch, and actor is the signed-in login: "source":"acme/roadmap@board".

A SQLite server reports "store":"sqlite", its database location and a source such as "sqlite:board". It uses the same routes and file hashes; revision identifiers address database snapshots rather than Git commits.

Every request carries the bearer

A card’s hash is the git blob SHA-1 of its file. GET /v1/cards/{id} returns it as hash and as the ETag header; every write returns the new one.

Routes read the board and edit one card at a time

fields accepts the fields update takes, plus tags, blocked_by and link; tags, blocked_by and assignee take a list. GET /editor/v1.js returns the description editor’s script and needs no bearer.

A doc or file target is a path from the card’s directory, such as report.md, or from the board as board/cards/<id>/report.md. A file elsewhere in the project, such as docs/research/analysis.md, gets 400 invalid_input. For a Git board, attach it with folio-agents board attach. SQLite file artifacts refer to files imported with the seed; the API does not upload new file contents.

A hosted GitHub server adds three sign-in routes

With a GitHub store and board.server.hosted set, the server answers its public host, signs people in with GitHub and takes a session instead of the printed bearer. SQLite uses the same login when board.auth.provider: github is selected. Explicit provider: token uses the configured workspace bearer instead.

In account mode, sign-in does not require access to the deployment repository. The person lists connected repositories, chooses a branch and directory, and exchanges that selection for a board-bound session. A board request without a selection answers 400 invalid_input. A repository outside both the person’s access and the App installation answers 403 read_only. GitHub permissions are checked again on each read and write. Readers cannot edit. Each commit is authored by the signed-in person and committed by the server.

With FOLIO_BOARD_MULTI_REPO=false, the server serves the single repository configured in board.store; only its collaborators can read it.

A hosted server clones the board’s branch at start into --workdir, replacing what was there, and reads its secrets from the environment: FOLIO_BOARD_SESSION_KEY (at least 32 bytes), FOLIO_BOARD_GITHUB_CLIENT_SECRET, and its own credential for the repository. That credential is a GitHub App installed on the repository, whose private key is in FOLIO_BOARD_GITHUB_APP_KEY or in the file FOLIO_BOARD_GITHUB_APP_KEY_FILE names: the server signs in as the App and renews its one-hour installation token on its own. Without an App key, it takes a token from the variable board.store.token_env names. People sign in with the same App, whose client id is board.server.hosted.github_client_id.

folio-board-server api --project-dir . --workdir /tmp/folio-board-clone

A write returns its revision

Card creation records board: add <id>, on either store.

Git stores create a commit. SQLite creates a database revision; the commit response field carries its identifier and message, with url: null.

{
  "rev": "f607a94…",
  "changed": true,
  "commit": {"sha": "f607a94…", "message": "board: ship-the-alpha done -> ideas", "url": null},
  "card": {"id": "ship-the-alpha", "hash": "b98e2fd…", "status": "ideas", "…": "…"},
  "diff": "",
  "warnings": []
}

A write whose result equals the card’s current bytes commits nothing and returns "changed": false. The server writes the commit message; a request cannot set one. The messages are those of the CLI, plus board: describe <id>, board: check criterion on <id>, board: update criterion on <id>, board: add criterion on <id> and board: detach <kind> from <id>. A request that makes two changes, such as a criterion’s done and text, commits as board: update <id>.

One error envelope, ten codes

{"error": {"code": "precondition_failed", "message": "'ship-the-alpha' changed since you read it",
           "hint": "review the current card and retry with its hash", "retryable": false,
           "current": {"id": "ship-the-alpha", "hash": "b98e2fd…", "…": "…"}}}

retryable is true for stale, and for a backend failure of git or the file system on /v1/board, a card read or a write, where the same request can succeed. Two backend answers carry false: a store failure on /v1/health, and a request whose worker task failed inside the server.

Three answers bypass the envelope and carry a plain-text or empty body:

No MCP server ships in this release

Not available in this release. Scripts and agents use this API for Git or SQLite. folio-agents board and the packaged skills operate Markdown/Git directories; they do not edit SQLite. Tool support compares the available interfaces.

Operation requests

POST /v1/ops and MCP’s card_apply call the same domain service. Set card to the id, ops to the operation list, if_match to the hash returned by GET /v1/cards/{id}, and dry_run to preview without committing.

{"card":"improve-search","ops":[{"op":"move","status":"in-progress"}],"if_match":"<current hash>","dry_run":false}

The service accepts move, update, set_description, toggle_criterion, set_criterion_text, add_criterion, comment, trail, attach and detach operations. Create a card with POST /v1/cards or MCP’s card_create instead of an op:create. Every write retains normal read-only and stale-hash checks. Neither actors nor commit messages are request fields. See API tokens and MCP.