Skip to content
Castellan
Reeve's icon

Reference · Reeve

Read as

Reeve's local API

The read-only endpoints on Reeve's page that other programs on this PC can poll (its state, its open alerts and Kept off the cloud), with their JSON.

Article
1212
Applies to
Reeve 0.17.2
Last reviewed
For
For developers
Written for Reeve 0.17.2. Reeve is at 0.17.3 now (1 small release since: what changed).

The rules#

  • This PC only. Reeve's page binds 127.0.0.1 alone, on port 18383 (28383 for a development checkout).
  • By its own names. It answers only a Host of reeve.localhost:<port>, 127.0.0.1:<port> or localhost:<port>, and 421 to anything else, so a web page can't reach it by a name of its own.
  • Reading needs no token. Everything below is read-only. What changes something (the page's buttons) needs the token the page carries, so another web page open in your browser can't press them.
  • JSON, never cached (cache-control: no-store). Times are ISO 8601, UTC; any is null when unknown.

GET /api/ping#

Whether Reeve is on duty, and its rounds' times. Castellan's card reads it.

{
  "app": "reeve",
  "running": true,
  "lastRunAt": "2026-10-09T14:30:41.000Z",
  "lastRunOk": true,
  "nextRunAt": "2026-10-09T15:00:00.000Z",
  "runningSince": null,
  "tour": true
}
FieldMeaning
runningOn duty.
lastRunAt, lastRunOkWhen the last run that ran a job ended, and whether every job it ran went through. A job that crashed, timed out or wrote a malformed result fails the run; a finding doesn't. A round with nothing due isn't a run.
nextRunAtThe next round at which a job is due. null off duty, with every job off or paused, or with no rounds task.
runningSinceWhile a run is going, when it started.
tourReeve's page has a tour, which Castellan offers once Reeve is hired.

GET /api/alerts#

The open alerts: each job whose last result is an alert. Cheap to poll. Castellan reads it for Needs you.

{
  "app": "reeve",
  "at": "2026-10-09T15:00:02.000Z",
  "page": "http://reeve.localhost:18383/",
  "offDuty": null,
  "toast": { "reeve": false, "why": "…" },
  "alerts": [
    {
      "id": "npu-health:3f9a1c0b7d2e",
      "job": "npu-health",
      "title": "Reeve's npu-health job: NPU driver changed: 30.0.140.1000 -> 30.0.145.1000",
      "detail": ["was 30.0.140.1000 (2026-09-30)", "Log: C:\\Users\\<you>\\.reeve\\runs\\npu-health\\…log"],
      "since": "2026-10-09T14:30:12.000Z",
      "checkedAt": "2026-10-09T14:30:12.000Z",
      "url": "http://reeve.localhost:18383/#job-npu-health"
    }
  ]
}
FieldMeaning
offDutySince when Reeve is off duty, else null. Off duty, the alerts are as last checked, and stay listed.
toastWhether Reeve raises its own Windows notification for a new alert, and why.
alerts[].idStable while the same thing is wrong: <job>:<12 hex>. A changed condition is a new id.
alerts[].titleOne line, at most 200 characters.
alerts[].projectsThe repositories it's about, when it names any.
alerts[].detailThe facts, one line each, at most 8, then the log's path.
alerts[].since, checkedAtWhen the condition began, and the round that last found it.
alerts[].urlThe job's row on Reeve's page.

Warnings aren't listed. An alert stays until a round's result for that job isn't one; acknowledging doesn't clear it. A broken job list answers 500 with { "error": "…" }.

GET /api/kept#

Kept off the cloud's totals: this month, last month and all time, with what each tool read. See Kept off the cloud.

From a terminal#

reeve status --json gives duty, the page, and every accelerator: its servers and whether each is ready, loading or down, whether it has failed (since when, and why), whether a game holds it, who holds each slot, and its line. See Reeve's command line.

Related articles

Is this page right?

If something on it is wrong or out of date, tell us and we'll fix the page.

Still stuck? Write to support@castellan-software.com and mention article 1212. Every version of Reeve, and what changed in it, is in its release notes.