Ask for what you want to know and Dialect sets it up. At the end you’ll have a running endpoint that a person has confirmed.
Ask for one
Say what you want to know, not how to read it. Dialect takes a photo, finds the thing, drafts typed fields, reads each one again on fresh photos and proposes the endpoint. You can do this from an agent, from the console under Endpoints with New endpoint, or over REST.
You should see a 201 with "state": "running" and an id.
| Field | What it is |
|---|---|
request | What you want to know, 3 to 2,000 characters. Required |
gateway_id | Which camera. Leave it out to let Dialect choose among those you may use |
time_zone | IANA name, used when you ask about schedules or “today” |
title | The title you want it to have |
Then call GET /v1/setup-runs/{id}/status, which holds for up to 20 seconds, until state isn’t running. A setup takes about 1 to 3 minutes. next always says what to do. POST /v1/setup-runs/{id}/stop stops one.
One setup runs at a time per workspace (409 busy), and a workspace can start 50 a day.
Read how a setup ended
ending | Means |
|---|---|
proposed | It worked. proposal holds what waits for a person |
no_camera | No gateway you may use could look |
not_in_view | The thing isn’t in the camera’s view |
cant_read_sure | It found the thing, but couldn’t read it sure enough to propose |
already_exists | An endpoint already answers this |
not_by_looking | A camera can’t answer this |
no_answer_fits, answers_split | The answers it tried didn’t fit, or disagreed |
stopped | Someone stopped it |
step_limit, time_limit | It ran out of room. Ask again, more narrowly |
refused | The request couldn’t be taken |
interrupted, internal_error, unexplained | Something failed on Dialect’s side. Try again |
Build one by hand
Most people should ask. To control every field, test a draft, then propose it. A draft must be tested within the hour, each field must read sure, and each target must be found.
A new endpoint must have a purpose, up to 200 characters. You may add why, up to 200 characters, for the person confirming it.
You should see the test’s state and what each field read, then a 201 for the proposal with its id, summary and "state": "proposed".
Fill in the endpoint
| Key | Rules |
|---|---|
name | Lowercase letters, digits and underscores, starting with a letter, 2 to 40 characters. Not test, versions or frames |
title | One line, 1 to 80 characters |
gateway_id | The gateway that reads it |
fields | 1 to 20, by name. Field names start with a letter, up to 40 characters |
every_s | Seconds between checks, 2 to 3,600. Default 5 |
record | changes (default) keeps changes and unsure readings. all keeps every check |
alerts | Up to 20 rules. See Alerts |
Choose its fields
type | Keys | Default bar |
|---|---|---|
choice | question, answers: 2 to 12, each answer’s name to what the photo shows | 0.9 |
yes_no | question, yes, no: what the photo shows for each | 0.9 |
level | question, levels: 2 to 7, lowest first | 0.8 |
colour | states: 2 to 12, each name to a list of 1 to 8 RGB colours. margin defaults to 20 | |
number | shows: digits or dial. question, unit, min, max. decimals (0 to 4) for digits. tolerance is required for a dial | 0.9 for digits |
text | question, max_length (1 to 200, default 60), pattern | 0.9 |
thresholdmay raise the bar, from 0.5 to 0.99, but not lower it below the default (bar_lowered).- A number outside
minandmaxis reported unsure. It’s never clamped. - A
patterncan’t use backreferences or lookaround. - Answer names can’t be
none_of_these,unknown,unavailable,not_in_vieworcovered. Those aren’t answers: Dialect reports them as missing. asksis the question shown to people, 3 to 80 characters. It doesn’t change the reading.
Every field says where to read:
| Key | What it is |
|---|---|
target | what names the thing in words, 3 to 120 characters. Dialect finds it again on each read, so a nudged camera still reads the right thing. inner is the part of it to read, as x, y, w, h fractions of the box found |
region | A fixed spot, as x, y, w, h fractions of the frame |
anchor | A fixed object nearby, 3 to 120 characters, that tells when the camera has moved |
Read flashing lights
A colour or choice field can name a state for a light alternating between two others, and a yes_no field can set blinking: true. over_s is how long to watch, 2 to 10 seconds, default 3. It’s sure only when the window clearly shows three changes or more at a steady rhythm.
Confirm an endpoint
An endpoint doesn’t run until a person confirms it. They open dialectlayer.com/endpoints, look under Waiting for you, check the photo and what each field reads, and select Start reading or Decline.
First Dialect reads a new proposal on 20 fresh photos, which takes about a minute. If any field reads sure on fewer than 15 of them, Dialect withdraws it, and it never shows under Waiting for you. Its state becomes declined, with dropped_why set to too_few_sure.
Over REST, a workspace administrator’s token can call POST /v1/endpoints/versions/{version_id}/confirm. Any other token gets 403. Signed-in agents never can, and no MCP tool does this.
| Route | Does |
|---|---|
POST /v1/endpoints/versions/{id}/decline | Declines a proposal. Agents may do this |
POST /v1/endpoints/versions/{id}/reopen | Undoes a decline within 10 minutes. too_late after that |
GET /v1/endpoints/versions/{id} | One version, with its state: proposed, active, paused, declined, stopped or replaced |
GET /v1/endpoints/{name}/versions | Every version of a name |
GET /v1/needs | Everything waiting for a person |
Change an endpoint
Propose the same name again. That makes its next version, and retires any earlier proposal.
- A change to
every_sor alerts alone runs at once, with no confirming. - Any other change waits for a person. The running version keeps running until they confirm.
PATCH /v1/endpoints/{name}withpurposeorlog_schedulechanges it in place, with no new version.
A gateway runs up to 50 endpoints. A name taken on a gateway you can’t use answers 409 name_taken.
Pause or stop an endpoint
| Route | Does |
|---|---|
POST /v1/endpoints/{name}/pause | The gateway stops checking. Reads give the last values with fresh: false and paused set. No webhook or alert email goes out, and its open alerts close with endpoint_paused |
POST /v1/endpoints/{name}/resume | Starts checking again |
POST /v1/endpoints/{name}/stop | Ends it. History stays, but programs reading it get 404. It can’t resume, so propose it again |
Paused endpoints still count toward your plan, and stopped ones don’t. See Billing.
Handle a re-aim
Cameras get bumped. When an endpoint has a lasting problem, Dialect tries to fix it by finding the thing again. A lasting problem means the camera has been out of place for 30 minutes with readings left unsure, or a field has had no sure value for over half of the last hour. Being covered, showing nothing, being paused or being offline don’t count.
It tries at most once a day per endpoint, never while a proposal waits, and not for a day after a person declines one.
A re-aim runs by itself only when all of this holds:
- It changes only where the field reads, its words or its anchor, and no field, answer, type, alert or timing.
- It’s the same object.
- It reads sure and the same on fresh frames.
Otherwise it waits for a person, like any proposal. If it can’t tell, dialect_endpoints shows a reaim with a question and choices. Ask the person, and pass their words to dialect_answer_reaim or POST /v1/setup-runs/{id}/answer. An agent must never answer it itself.
A workspace administrator can undo one with POST /v1/endpoints/versions/{id}/undo-reaim, which also holds re-aims off for a day.
Dialect may also reword a question that keeps reading unsure, tested against kept photos. This never changes what the field returns. POST /v1/endpoints/versions/{id}/restore-wording puts it back.
Schedule a log
To record a value at set times, like a round on a clipboard, give an endpoint a log_schedule: 1 to 24 times as HH:MM, weekdays from mon to sun, and a time_zone.
Read the entries with GET /v1/endpoints/{name}/log, or as a spreadsheet with GET /v1/endpoints/{name}/log.csv (up to 400 days). Each entry’s state is read, unsure or missing. A person can settle an unsure entry with POST /v1/endpoints/{name}/log/{entry_id}/read. null as the schedule clears it.