Read an endpoint

Get current values, follow changes, ask about a time window, and handle unsure readings.

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

Read an endpoint

You should see:

Response with current values

The keys you’ll use most:

KeyMeans
valueThe value, as the field’s type
qualityvalid, uncertain or none. See Tell sure from unsure
doubt, missingWhy it’s unsure, or why there’s no value
freshWhether it’s current. False while paused or offline, after a failed read, or when not confirmed lately
sinceWhen it took this value
observed_atWhen it was last confirmed, by a read or by a check that the picture hadn’t changed
read_atWhen it was last actually read
failed_atWhen the latest read failed, while the value held is from before
last_sure{value, at}, the last sure value, only beside an unsure one
sourcegateway, 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.

Act only on sure, fresh values
  • An unsure value is a best reading. Show it as one, or use last_sure, but don’t act on it.
  • null always comes with a missing, and only a null does.
  • While the camera is moved or lost, a sure value read from a fixed spot or a held target turns unsure with camera_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.

List recent changes
ParameterMeans
afterRows after this id, oldest first. Default 0
newest, beforeNewest first, and older than this id
fieldOne field
limitDefault 50, at most 200
since, untilA time window
unsuretrue for only unsure rows
valueOnly 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.

Summarize today from 06:00

You should see:

Response with time in each value

Choose one window:

ParametersWindow
last_sThe 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 untilAny 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

RouteGives
GET /v1/pictures/{picture_id}?size=thumb or size=fullThe JPEG behind a history row
GET /v1/endpoints/frames/{frame_id}A kept frame as a JPEG
POST /v1/endpoints/{name}/lookA 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.

PictureKept for
Routine frames7 days
Photos from looks and tests14 days
Pictures of changes90 days
Alert and log entry pictures365 days

Next steps