Read what’s true now, what changed, and how long something held. At the end you’ll know when a value is safe to act on. Times over REST are Unix seconds.
Read current values
You should see:
The keys you’ll use most:
| Key | Means |
|---|---|
value | The value, as the field’s type |
quality | valid, uncertain or none. See Tell sure from unsure |
doubt, missing | Why it’s unsure, or why there’s no value |
fresh | Whether it’s current. False while paused or offline, after a failed read, or when not confirmed lately |
since | When it took this value |
observed_at | When it was last confirmed, by a read or by a check that the picture hadn’t changed |
read_at | When it was last actually read |
failed_at | When the latest read failed, while the value held is from before |
last_sure | {value, at}, the last sure value, only beside an unsure one |
source | gateway, or dialect when Dialect looked at the whole frame again because the gateway’s reading had nothing to rely on |
The endpoint’s own fresh is true when it was checked recently, its gateway is online and every field is fresh. seen lists the states each field has been seen in, and the ones not yet.
GET /v1/endpoints/{name}/schema gives the JSON Schema of values. GET /v1/endpoints lists them all, with starting, gateway_online and gateway_heartbeat_at as well.
Over MCP, dialect_read_endpoint gives a shorter answer, with since in ISO UTC. Pass response_format: "detailed" for every key.
Handle unsure values
Act on a value only when quality is valid and fresh is true. Otherwise say you don’t know.
- An unsure
valueis a best reading. Show it as one, or uselast_sure, but don’t act on it. nullalways comes with amissing, and only anulldoes.- While the camera is
movedorlost, a sure value read from a fixed spot or a held target turns unsure withcamera_moved. One whose target was found in that very read stays valid. - A brand-new state is unsure at first, with
doubt: "unseen", until Dialect agrees with it.
Follow changes
History gives one endpoint’s changes and unsure readings.
| Parameter | Means |
|---|---|
after | Rows after this id, oldest first. Default 0 |
newest, before | Newest first, and older than this id |
field | One field |
limit | Default 50, at most 200 |
since, until | A time window |
unsure | true for only unsure rows |
value | Only this value, as JSON such as "open" or true. Needs field, and can’t go with unsure |
You should see {changes, after, before, total, older, newer}. Each row has id, field, value, quality, observed_at, received_at, previous as {value, quality}, what_changed as value, certainty, nothing or first, and has_photo. late is true when it was heard more than a minute after it was observed. Rows with the field _camera are the camera’s own checks.
To follow every endpoint, poll GET /v1/endpoint-changes?after={last_id}&limit=50 from the last id you saw. Or let webhooks tell you.
Ask how long and how often
since isn’t how long it held today. For that, use the summary.
You should see:
Choose one window:
| Parameters | Window |
|---|---|
last_s | The last so many seconds, up to 31 days |
time_zone, days_ago (0 to 31), start (HH:MM) | One day, today by default, from start to now or midnight |
since and until | Any span up to 31 days |
Add field for one field. Without a zone, Dialect uses the one the endpoint keeps. If it keeps none, you get 422 asking for time_zone.
For each value you get its seconds, its share and how many times it was entered. A number gives min, max, average and readings instead. Sure, unsure and unknown time add up to the window, and unsure_s_by_why splits the unsure time by its reason.
Get pictures
| Route | Gives |
|---|---|
GET /v1/pictures/{picture_id}?size=thumb or size=full | The JPEG behind a history row |
GET /v1/endpoints/frames/{frame_id} | A kept frame as a JPEG |
POST /v1/endpoints/{name}/look | A fresh frame now. Needs a paid plan |
Readings aren’t deleted. Pictures go on a schedule, and a row’s has_photo then turns false.
| Picture | Kept for |
|---|---|
| Routine frames | 7 days |
| Photos from looks and tests | 14 days |
| Pictures of changes | 90 days |
| Alert and log entry pictures | 365 days |