Regions¶

Nerthus.Core (until cutover). This page describes the frozen system that runs today and is deleted at cutover. Replaced by: not yet written.

A Region is a named, time-scoped grouping of locations — the concept is owned by the region model. This page owns the routes: listing regions, reading one region with its members computed as of a date, and creating or editing region blocks. The fixture ships no regions, so the examples below create Południowa Elancja first and build on it in order. Region names carry spaces and diacritics, so every path segment below is URL-encoded.

Reads need entity.read, writes need entity.write. Every example runs 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.

GET /regions/{name} takes ?activeOn= (membership as of a date; default: now) and ?recurse=true (the transitive closure over nested regions — the default is direct members only). Membership itself is one temporal @region line on the member Lokacja, written through PATCH /locations/{name} — that route's row is owned by Locations & maps.

Create a region¶

POST /v1/api/regions forces type = Region, so the body needs only a name. The block lands under the ## Region index section, and the follow-up read proves it exists. The importer mints no regions — this route and hand-authored blocks are the only two ways a Region comes to exist.

POST /v1/api/regions
Content-Type: application/json
Authorization: Bearer <token>

{ "name": "Południowa Elancja" }

await fetch("https://evocation.nerthus.pl/v1/api/regions", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
  body: JSON.stringify({ name: "Południowa Elancja" }),
});

Response 201:

{ "created": "Południowa Elancja", "type": "Region" }

List regions¶

GET /v1/api/regions returns the { count, items } envelope of every Region projection, each with its direct MemberCount as of ?activeOn= (default: now). Exactly the one region created above, still memberless.

GET /v1/api/regions
Authorization: Bearer <token>

await fetch("https://evocation.nerthus.pl/v1/api/regions", {
  headers: { "Authorization": `Bearer ${token}` },
}).then((r) => r.json());

Response 200:

{ "count": 1, "items": [
  { "Name": "Południowa Elancja", "Type": "Region", "Status": "Aktywny", "MemberCount": 0 }
] }

Put a place in the region¶

Membership is one temporal @region line on the member, written with the location PATCH route (Locations & maps owns its row). The value carries the range suffix, so the membership holds from April 2020 onward.

PATCH /v1/api/locations/Thuzal
Content-Type: application/json
Authorization: Bearer <token>

{ "tag": "region", "value": "Południowa Elancja (2020-04:)" }

await fetch("https://evocation.nerthus.pl/v1/api/locations/Thuzal", {
  method: "PATCH",
  headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
  body: JSON.stringify({ tag: "region", value: "Południowa Elancja (2020-04:)" }),
});

Response 200:

{ "updated": "Thuzal", "tag": "region", "changed": true }

Fetch one region with its members as of a date¶

GET /v1/api/regions/{name} returns { Region, Members, MemberCount } — the region's projection plus its member headings computed as of ?activeOn=. Direct members by default; ?recurse=true unions nested regions' members. An unknown name is 404 ({ "error": "Region not found" }). In July 2026 Thuzal is a member; the follow-up probe asks about January 2020, before the membership range opens, and finds none — the same data, two dates, two answers.

GET /v1/api/regions/Po%C5%82udniowa%20Elancja?activeOn=2026-07-01
Authorization: Bearer <token>

await fetch("https://evocation.nerthus.pl/v1/api/regions/Po%C5%82udniowa%20Elancja?activeOn=2026-07-01", {
  headers: { "Authorization": `Bearer ${token}` },
}).then((r) => r.json());

Response 200 (trimmed):

{ "Region": { "Name": "Południowa Elancja", "Type": "Region", "Status": "Aktywny" },
  "Members": ["Thuzal"], "MemberCount": 1 }

Update a region tag¶

PATCH /v1/api/regions/{name} sets one tag from the closed schema on the region block — here an @alias. An unknown tag is 422. The follow-up read shows the alias on the projection.

PATCH /v1/api/regions/Po%C5%82udniowa%20Elancja
Content-Type: application/json
Authorization: Bearer <token>

{ "tag": "alias", "value": "Elancja Południowa" }

await fetch("https://evocation.nerthus.pl/v1/api/regions/Po%C5%82udniowa%20Elancja", {
  method: "PATCH",
  headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
  body: JSON.stringify({ tag: "alias", value: "Elancja Południowa" }),
});

Response 200:

{ "updated": "Południowa Elancja", "tag": "alias", "changed": true }