Skip to content

Local REST API

The Provider Client exposes a small HTTP API on the machine where it runs — for health, busy status, and a status dashboard. These routes are local only. Flockadoo does not call them over the provider connection; health is sent from the client to Flockadoo on a schedule.

The base URL is the client’s server (host and port from config). For example, http://localhost:8080. The default bind is 127.0.0.1, so these routes are only reachable from that machine.

If the client runs in Docker, the connection to Flockadoo does not need a published port. To open the dashboard from the host, set server.host to 0.0.0.0 and publish the port to loopback on the host (for example -p 127.0.0.1:8080:8080). See Configuration.

There are no /health or /busy aliases — use the /api/... paths below.

GET /

Browser status page with the same information as the terminal UI. It shows session, models, GPU, and recent inference requests. On a Team Flock machine, FLOCK STATUS also shows Flock, Nodes, Winglink IP, and Peers. The terminal adds an Engine line. The page refreshes automatically. See Read status on the machine.

GET /api/status

JSON snapshot of that status page. Includes session status, a masked provider API key, models, GPU, recent inference requests, last health update, and whether the client is connected to Flockadoo.

capabilities is an array of {name, state, detail}. state is waiting, testing, supported, unsupported, or unverified. capability_line is the summary, for example testing - 2/5 checked (still serving requests). Session status stays online while those checks run.

On a Team Flock machine the same object adds:

Field Example Meaning
flock master master, worker, or single
nodes 1/4 This machine plus online peers, out of the flock size
winglink_ip 198.18.0.2 This machine's address on the private network
peers 3 online Other machines that are online. Omitted when none are

GET /api/health

Current health snapshot: GPU (when available), models from the local LLM server, and provider_type.

GET /api/busy

Whether the client considers itself busy.

{ "busy": false }

busy is true only when every inference slot is full. The default is 1 slot (max_concurrent_inference). The same rule applies on Linux, Windows, and macOS. The health report’s GPU is_busy flag is a separate check — see How it works.

Inference routes (not for operators)

Flockadoo sends work to POST /v1/chat/completions, POST /v1/completions, and POST /v1/embeddings over the provider connection. Those routes require a signed X-Request-Id from the platform. Do not call them yourself — you will get 401.

When every inference slot is full and the request is not a follow-up for the same session, the client returns 503 {"error":"GPU is busy"} so Flockadoo can try another provider. Unverified models return 403. LLM failures return 502.

Platform: client version

These are Flockadoo platform routes, not the local client API. The client calls them with X-Flockadoo-Client-Version.

GET /api/client/version

No API key. Returns the newest release and the oldest release Flockadoo still accepts.

{
  "latest": "1.4.0",
  "min_supported": "1.2.0",
  "download_url": "https://github.com/flockadoo/flockadoo/releases/latest",
  "support_window_days": 90
}

min_supported is an empty string while every release is accepted.

426 Upgrade Required

A provider route returns this when the client is older than min_supported.

{
  "error": "client_outdated",
  "min_version": "1.2.0",
  "latest_version": "1.4.0",
  "download_url": "https://github.com/flockadoo/flockadoo/releases/latest"
}

Successful responses include X-Flockadoo-Latest-Client-Version. See Updating the client.