Appearance
observations
13 endpoints at a glance
| Method | Path | Summary |
|---|---|---|
GET | /observations/events/ | List Events |
POST | /observations/events/ | Create Event |
DELETE | /observations/events/{event_id} | Delete Event |
GET | /observations/events/{event_id} | Get Event |
PUT | /observations/events/{event_id} | Update Event |
POST | /observations/events/{event_id}/collect | Collect Event |
GET | /observations/events/{event_id}/matrix | Event Matrix |
GET | /observations/events/{event_id}/narrative | Get Narratives |
POST | /observations/events/{event_id}/narrative | Generate Narrative |
GET | /observations/events/{event_id}/pair | Event Pair |
POST | /observations/events/{event_id}/resolve | Resolve Event |
GET | /observations/events/{event_id}/trend | Event Trend |
GET | /observations/events/{event_id}/trend/pair | Event Trend Pair |
observations
List Events
Create Event
POST
/observations/events/
Create an event (unresolved). 400 on invalid window / sources / coords.
Parameters
Header Parameters
authorization
x-api-key
Request Body
application/json
JSON "event_ts": 0, "window_minutes": 0, "sources": [ { "lat": 0, "lon": 0, "label": "string" } ], "label": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Get Event
Update Event
PUT
/observations/events/{event_id}
Edit an event's config (date/time, window, source points, label).
Changing an analysis-affecting field resets the derived selection + mesh
fetch record (re-resolve to recompute); a label-only edit keeps them. Never
deletes collected results in measurements_results. 400 on invalid
config; 404 if the event is gone.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Request Body
application/json
JSON "event_ts": 0, "window_minutes": 0, "sources": [ { "lat": 0, "lon": 0, "label": "string" } ], "label": "string"
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Delete Event
Resolve Event
POST
/observations/events/{event_id}/resolve
(Re)compute the Step-1 selection (10 nearest connected-at-(T−W)
anchors per source + window profiles). Synchronous (DB-only).
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Collect Event
POST
/observations/events/{event_id}/collect
Step 2 — collect the 20-anchor mesh traceroute results over the window
from RIPE and upsert into measurements_results. Fire-and-forget (RIPE
network calls outlive the gateway timeout); poll GET /{id} and watch
mesh.fetch_status. Requires a resolved selection.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Event Matrix
GET
/observations/events/{event_id}/matrix
Step 3 — per-pair traceroute metric series + pre-event baseline for the
delta mesh-matrix, for one IP family (af 4 or 6). Requires the event to
be resolved + collected.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Query Parameters
af
Type
integer
Default
4Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Event Pair
GET
/observations/events/{event_id}/pair
Step 3 drill-down — per-timestamp parsed traceroute path + metrics for
one ordered src → dst probe pair across the window.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Query Parameters
src*
Type
Requiredinteger
dst*
Type
Requiredinteger
af
Type
integer
Default
4Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Event Trend
GET
/observations/events/{event_id}/trend
Trend mode (long windows) — per-pair pre-vs-post ping deltas (RTT median,
loss %, reachability) over the RIPE ping-stats downsample. The long-window
analog of the traceroute matrix; no path/reroute data. Requires a done
trend collect (window_minutes > 60).
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Query Parameters
af
Type
integer
Default
4Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Event Trend Pair
GET
/observations/events/{event_id}/trend/pair
Trend drill-down — the stored ping-stats bucket series (sent/received,
loss %, RTT 5/50/95pct per bucket) for one ordered src probe → dst anchor pair, plus the pre-event baseline RTT.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Query Parameters
src*
Type
Requiredinteger
dst*
Type
Requiredinteger
af
Type
integer
Default
4Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Get Narratives
GET
/observations/events/{event_id}/narrative
Stored narratives for an event — at most one per model alias, so a
chat and a reasoner take can be compared side by side. Each row
carries the evidence packet it was written from, for audit.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}
Generate Narrative
POST
/observations/events/{event_id}/narrative
Generate an incident narrative for the event (fire-and-forget).
A deterministic evidence packet is computed from the collected
analysis and DeepSeek is asked only to narrate it; output containing
any figure the packet doesn't support is rejected. Backgrounded — the
completion outlives the gateway timeout — so poll
GET /{id}/narrative.
400 on an unknown model alias, or when the event isn't resolved +
collected yet. Everything else (no API key, budget spent, upstream
error, ungrounded output) is recorded on the narrative row as a
failed status so the UI can show why.
Parameters
Header Parameters
authorization
x-api-key
Path Parameters
event_id*
Type
Requiredstring
Request Body
application/json
JSON "model": "string", "force": false
{
}
Responses
Successful Response
application/json
JSON "additionalProperties": "string"
{
}