API reference

1. Overview & conventions

Base URL and media types

Conventions

• Timestamps are RFC 3339 strings (e.g. 2026-07-05T14:02:00Z).
• Enum values render as their proto names (WILDFIRE, ACTIVE, SEVERE). Query parameters accept them case-insensitively, and layer parameters additionally accept the lowercase layer slugs used in .geojson paths (wildfire).
• Repeatable filters: parameters documented as repeatable may appear multiple times — ?layer=wildfire&layer=evacuation.
• Pagination is cursor-based on the event lists — events, events/{id}/history, and history: pass the opaque nextPageToken from a response as the page_token query parameter on the next request (base64 keyset cursors; treat them as opaque). The directory lists — places, sources, and scanners — are not paginated: each returns its complete set in one response by design (a bounded, slowly-changing directory), with no nextPageToken. Read them whole; don't build paging logic for them.
• Query parameters stay snake_case regardless of response casing: severity_min, page_token, page_size (camelCase forms are also accepted).
• ETags: most read endpoints carry a weak ETag; a conditional request with a matching If-None-Match gets 304 Not Modified and skips the work. Coverage: events/{id} + .../history, the events and history lists, places + places/{place}, and the .geojson layers (body-hash). Not yet instrumented: conditions, sources, places:resolve, scanners, and summary. Independently, every proto RPC carries Cache-Control: public, max-age=30, so a proxy/CDN may serve any of them up to 30 s stale (the .geojson layers use max-age=60).
• Errors from the proto RPCs are gRPC-standard {code, codeName, message, details} alongside the mapped HTTP status; the one hand-built endpoint (.geojson) emits the older google.rpc.Status shape ({code, message, details}, no codeName):

HTTP/1.1 404 Not Found
Content-Type: application/json

{"code": 5, "codeName": "NOT_FOUND", "message": "event not found"}

code is the numeric gRPC status code (5 = NOT_FOUND, echoed as codeName). Clients should key on the HTTP status and surface message.

• Canonical client sort for events: severity descending, then observedAt descending.
• Places are addressable by slug or id: ebbetts-pass and area:ebbetts-pass both work anywhere a {place} appears. Slugs are globally unique (§4).

CORS

All /api/v1 endpoints are served with open CORS — any origin can fetch them from a browser. This site is itself an unprivileged client of that same surface: every number on every page here is a same-origin browser fetch you can replay with curl (see the footer of any page).

2. Endpoint reference

Two idioms, one rule: entities (events, places, sources, conditions, scanners) are global collections filtered by query parameter; place-derived documents (summary, map layers) nest under the place path. The two hot paths — summary and map layers — take no query string at all, so CDN cache keys stay clean.

Every entry expands to its parameter table and example requests. The examples are not illustrations: press RUN and the page fetches that exact URL live and prints the real response, status, timing and byte count. An example that has gone stale therefore fails in front of you rather than quietly misleading you.

3. The Event envelope

Every discrete occurrence is one grid.v1.Event message. The common envelope is identical across layers — a client can render any event's card from headline / severity / provenance / observedAt without knowing its kind. Typed per-kind data lives in exactly one detail block.

Fields, beside a live record

Every field

Detail blocks (the oneof)

Each block carries only kind-specific fields. Anything already in the envelope is not repeated: the incident/alert type is category, the human location is areaLabel, the short line is headline, the sending office is provenance.sourceName, and the source page is canonicalUrl.

Unit-bearing fields name their unit (depthKm). A fire_weather detail slot is reserved in the schema but fire weather is condition-backed (a map layer, not an event stream). The mesh block's telemetry is the last-heard signal state and is volatile — it never mints a new event revision (only a node's identity, role, name, location, or status does). For "when did this node last advertise", the trustworthy answer is the event's observedAt (when the Grid last heard it); telemetry.lastAdvertAt is the node's self-reported stamp and is diagnostic only (mesh node clocks skew). Slots are also reserved for future layers: power, gauge, air_quality, announcement.

Enum: Layer

road_segment and chain_control are condition-backed map-layer slugs only — they are projections of live road state, not Layer enum values, and never appear in /api/v1/events.

Enum: Severity (the canonical scale + color ramp)

One comparable scale across every source. It expresses response urgency to the public, not physical magnitude — an Evacuation Order (EXTREME) intentionally outranks an M5 earthquake (SEVERE). Rank equals the enum value. Always pair the color with the text label — color is never the only signal.

There are two ramps, not one: the same severity resolves to a print-weight colour on paper and a lighter, foreground-tuned one inside the black data panes, because no single value is legible on both. Ranks and enum names are identical across them — only the rendering differs, and the swatch is only ever a second signal beside the always-present text label.

Enum: EventStatus (lifecycle)

SCHEDULED ──▶ ACTIVE ──▶ RESOLVED   (upstream confirmed over)
                   └──▶ EXPIRED    (aged out; upstream went quiet)

Every status transition writes a revision — the all-clear is part of history. By default /api/v1/events returns only ACTIVE,SCHEDULED; closed events remain queryable by passing status= explicitly and through /api/v1/history.

Geometry and the base64 note

Event.geometry is {geojson: bytes, bbox: {minLat, minLng, maxLat, maxLng}, centroid: {lat, lng}}. The geojson field is a raw RFC 7946 geometry object stored as proto bytes — protojson renders bytes as base64, so decode before parsing:

const g = event.geometry;                          // may be absent entirely
const geom = g?.geojson ? JSON.parse(atob(g.geojson)) : null;
// geom is an RFC 7946 geometry object — coordinates are [lng, lat]

bbox and centroid are always populated at ingest when geometry exists, so list views never need to decode. For map rendering, prefer the .geojson endpoints — the base64 field exists for detail views.

4. Places & the id scheme

Place ids are {kind}:{slug}. Slugs are globally unique, so every place is addressable by bare slug (ebbetts-pass) or full id (area:ebbetts-pass) anywhere a {place} path segment or place= parameter appears. Area slugs are short, stable ids (e.g. ebbetts-pass).

Each Place carries id, kind, name, slug, geometry, parentId. Parent links: towns point at their county; areas have no parent. /api/v1/places:resolve returns containing places ordered most-specific-first: SITE, EVAC_ZONE, TOWN, CORRIDOR, COUNTY, AREA.

5. The GeoJSON layer contract

Each /api/v1/places/{place}/map/{layer}.geojson response is one RFC 7946 FeatureCollection with a foreign top-level metadata member (allowed by RFC 7946, ignored by map libraries, available to clients that read it):

{
  "type": "FeatureCollection",
  "features": [ … ],
  "metadata": {
    "layer": "evacuation",
    "area": "ebbetts-pass",
    "generatedAt": "2026-07-05T15:42:11Z",
    "sourceStatus": "OK",             // OK | STALE | UNAVAILABLE
    "lastSourceUpdate": "2026-07-05T15:38:00Z",
    "attribution": "Cal OES / California County Governments — reference only",
    "sourceUrl": "https://protect.genasys.com/…",
    "schemaVersion": 1
  }
}

metadata.sourceStatus

Layers are fail-loud: a source error never becomes a fabricated clear state. The three states render differently and must not be collapsed:

The properties envelope

Every feature, in every layer, shares one common envelope — that is the unification. A client renders any feature's card from headline / severity / source / updatedAt without knowing its kind:

{
  "type": "Feature",
  "geometry": { "type": "Point", "coordinates": [-120.5402, 38.0674] },
  "properties": {
    // ---- common envelope (present on every feature) ----
    "id": "calfire:2026-salt-springs",   // globally unique, source-namespaced
    "layer": "WILDFIRE",                 // Layer enum name (same value as event.layer)
    "kind": "Wildfire",                  // human label
    "category": "active",                // source sub-type slug (free-form, lowercase)
    "severity": "SEVERE",                // unified scale, §3
    "severityRank": 3,                   // 0..4, for sort/color
    "headline": "Salt Springs Fire — 1,377 ac, 20% contained",
    "description": "…",                  // optional, long
    "status": "ACTIVE",                  // EventStatus enum name (lifecycle)
    "effective": "2026-07-05T14:02:00Z", // RFC 3339, nullable
    "expires": null,
    "updatedAt": "2026-07-05T15:40:00Z",
    "areaLabel": "Hathaway Pines & Avery",   // optional
    "source": {
      "id": "calfire", "name": "CAL FIRE",
      "url": "https://www.fire.ca.gov/incidents/…",
      "attribution": "CAL FIRE / FIRIS",
      "fetchedAt": "2026-07-05T15:42:10Z"
    },
    // ---- per-kind typed block (only the relevant one) ----
    "wildfire": { "acres": 1377, "containment": 20, … }
  }
}

• Per-kind data lives under a single namespaced key (wildfire, earthquake, evacuation, weather, incident, power, mesh) — consumers ignore kinds they don't handle; no field collisions.
• Coordinate order is [longitude, latitude] (GeoJSON axis order), WGS84, trimmed to 5 decimals (~1.1 m). Polygons are simplified to keep features small.
• Null geometry is valid (e.g. a county-wide advisory): the feature has "geometry": null with the same properties envelope. Exclude it from the map layer and render it as a full-width banner/list card sorted by severityRank alongside located features, showing headline, source.name, updatedAt, and source.url.
• URL fields are scheme-validated upstream: any upstream-sourced URL that is not https:///http:// is dropped before it reaches the response. Treat all upstream text (headlines, descriptions) as untrusted anyway.
• Unit-bearing fields name their unit (windGustMph, depthKm).
• layer has two forms, by role. As a value — properties.layer here, and event.layer / topEvents[].layer elsewhere — it is the UPPERCASE Layer enum name (WILDFIRE). As an address — the {layer} path segment, the ?layer= query value, and the metadata.layer / metadata.area echoes above — it is the lowercase slug (wildfire). One rule: values are enum names, URLs and the metadata block are slugs. Mesh-node presence is the one layer whose slug (mesh_node) is not just the lowercased enum name (MESH): as a ?layer= value the query accepts mesh (the enum name), mesh_node (the slug), and the legacy network — all resolve to the same layer. (Before 2026-07-25 this layer's enum was NETWORK; it was renamed to MESH, with network kept as a legacy query alias.)
• This endpoint is not in the OpenAPI spec. The .geojson layers are hand-built (RFC 7946 geometry doesn't model cleanly in proto3), so a client generated from the spec alone will be missing all eight map layers — integrate them from this section.

7. Source registry

Every event and every layer traces to one of these sources — the registry behind /api/v1/sources (live board: Sources). Each Source carries id, name, attribution, homepageUrl, pollIntervalSeconds, staleAfterSeconds, expireAfterSeconds, lastSuccessAt, lastAttemptAt, lastError, status. A source is STALE once its last success is older than staleAfterSeconds (default 3× its poll interval) and UNAVAILABLE on persistent failure.

A poller may update multiple source rows (the wildfire tick updates calfire + firis; the incidents tick updates chp + caltrans) — poller ≠ source. Poll intervals and staleness thresholds are server configuration; read the live values from /api/v1/sources rather than hard-coding this table.

Attribution requirements

• Display the attribution string (from Source.attribution, Event.provenance.attribution, or metadata.attribution on GeoJSON layers) wherever you render the data.
• Link the upstream: provenance.sourceUrl (events) / metadata.sourceUrl (GeoJSON) on records, homepageUrl on the source.
• Evacuation data must carry its reference-only framing and the Genasys link in every state (§6).

8. Push ingest (operator-reported data)

This is the only write endpoint on the API, and the only one that requires a credential. Everything else on /api/v1 is public, read-only and keyless; nothing below changes that. It exists for data no upstream feed publishes — an operator's monitor that logs into MeshCore repeaters and reads their admin interface, which is the only way to obtain battery, airtime and packet counters, and the only input that can report a node it tried to reach and could not.

POST /api/v1/ingest/{stream}

Requires Authorization: Bearer <token>. Tokens are issued per reporter by the operator; only a SHA-256 hash of the token is stored in configuration, so the credential itself never appears in this project's public repository. The endpoint is not mounted at all unless a reporter is configured, and the CORS policy (corsAllowMethods: [GET]) leaves it unreachable from a cross-origin browser page.

Success is 202 Accepted, not 200: the report has been authenticated and validated, but it is not yet in the store — the next ingest tick merges it. The response is {reporterId, stream, accepted, warnings, receivedAt}. A malformed entry is a warning, not a rejection — one repeater with a typo'd id must not cost the operator the other eight — while a malformed envelope rejects the whole request.

Stream mesh.repeater (schema_version 1)

POST /api/v1/ingest/mesh.repeater
Authorization: Bearer <token>

{
  "schema_version": 1,
  "generated_at": "2026-09-15T00:23:32+00:00",
  "repeaters": [
    {
      "id": "de0715314cfa9b5e",          // public key, or a prefix of one (≥8 hex)
      "name": "SIERRA Arnold Summit",
      "last_attempt": 1789431672,         // unix seconds
      "last_success": 1789431672,         // null if never reached
      "battery_voltage": 4.14, "battery_percent": 97.0,
      "battery_percent_source": "estimated",
      "temperature_c": 37.0, "humidity": null, "pressure": null,
      "uptime_s": 2615083, "airtime_ms": 49646, "rx_airtime_ms": 211238,
      "noise_floor_dbm": -116, "last_rssi_dbm": -88, "last_snr_db": 12.5,
      "tx_queue_len": 0,
      "nb_sent": 150305, "nb_recv": 649331,
      "sent_flood": 149984, "sent_direct": 321,
      "recv_flood": 642043, "recv_direct": 6702,
      "direct_dups": 53, "flood_dups": 30331,
      "full_evts": 0, "recv_errors": 240197,
      "online": true
    }
  ]
}

• A report is the reporter's COMPLETE current set. A node omitted from a report is treated as no longer monitored, the same contract a poller's result has with the disappearance sweep. Send every node you watch, every time.
• Unread values must be null, never 0. A null gauge is published as absent; a zero is published as a measurement. A node that has never been reached (last_success: null) is published with no telemetry block at all rather than a row of zeroed counters.
• Timestamps are clamped to server time. A stamp in the future is treated as "now" — a monitor's clock is not ours.
• Reposting an identical report is harmless: entries are keyed by node, so a retry after a network failure overwrites rather than duplicates.

How it surfaces

• One event per node, not one per input. A node reported by a monitor and heard over MQTT resolves to the same event id — a reported prefix is matched against the known node catalog. While a node is known only by prefix its id is meshcore:{prefix}; once an advert supplies the full key, the event id becomes meshcore:{full key} and the prefix-keyed event is retired as superseded. Don't treat a mesh event id as permanent for a node not yet heard over MQTT.
• mesh.reachability — REACHABLE | UNREACHABLE. A node no monitor watches has neither, and must not render as one that is down: on /api/v1/events it reads MESH_REACHABILITY_UNSPECIFIED (the gateway emits unpopulated fields), and on the .geojson layer the property is omitted. It is derived from the age of the last success, not from the reporter's online flag, so a single missed poll does not flip it. It is part of the event's content hash, so a transition appears in /api/v1/events/{id}/history.
• mesh.telemetry.admin — the last sample, with reporterId and lastSuccessAt. It is excluded from the content hash, so frequent reporting refreshes these values without creating a revision per report: poll events/{id} for current values, and expect /history to show only meaningful changes.
• A node known only to a monitor has no geometry — a report carries no coordinates and the Grid does not invent them — so it appears in /api/v1/events?layer=mesh and, where the operator has configured a place attachment, in place-scoped views, but its mesh_node map feature has "geometry": null until an advert supplies a position.