Discovery & health¶

Four public routes let a client learn about the daemon before it holds a token: whether it is up, the closed schema vocabulary it enforces, the format-version pointer, and the full route table. All four carry a null capability — no Authorization header, no auth. Every example below runs anonymously against a live daemon — see how the reference is tested.

Routes¶

Cap is the required capability (— = public, no token); Write (✓) marks routes that pass the write gate; a — in Cmdlet is reached directly, no wrapper. Paths are relative to /v1/api; the cross-cutting contract — middleware, envelopes, status codes — is on the API reference index.

Health¶

GET /v1/api/health is the liveness probe. It returns status: "ok", the on-disk and expected schema versions, the current mode, uptime, request count, the loaded entity count, and the process id.

GET /v1/api/health

await fetch("https://evocation.nerthus.pl/v1/api/health").then((r) => r.json());

Response 200 (trimmed):

{ "status": "ok", "schema": "0.8.0", "expected": "0.8.0", "mode": "ReadWrite", "entities": 26, "pid": 40122 }

Schema¶

GET /v1/api/schema returns the closed vocabulary the daemon validates against: the seven entityTypes, the statuses, the tag schema, denominations, towns, roles, and the derived capabilities.

GET /v1/api/schema

await fetch("https://evocation.nerthus.pl/v1/api/schema").then((r) => r.json());

Response 200 (trimmed):

{ "entityTypes": ["NPC", "Grupa", "Lokacja", "Mapa", "Gracz", "Postać", "Przedmiot"],
  "statuses": ["Aktywny", "Nieaktywny", "Usunięty", "Niepewny"] }

Schema version¶

GET /v1/api/schema/version is the format-version pointer: the version stamped onDisk against the expected version this daemon build requires. A mismatch is what puts the daemon into read-only mode.

GET /v1/api/schema/version

await fetch("https://evocation.nerthus.pl/v1/api/schema/version").then((r) => r.json());

Response 200:

{ "onDisk": "0.8.0", "expected": "0.8.0" }

Routes¶

GET /v1/api/routes returns the entire closed route table — count plus one row per route with its method, path, required capability (null for a public route), and write flag. This is the self-description a client reads to discover the API.

GET /v1/api/routes

await fetch("https://evocation.nerthus.pl/v1/api/routes").then((r) => r.json());

Response 200 (trimmed):

{ "count": 84, "routes": [
  { "method": "GET", "path": "/v1/api/health", "capability": null, "write": false },
  { "method": "GET", "path": "/v1/api/schema", "capability": null, "write": false }
] }