Set up an endpoint

Ask for one in a sentence or build it by hand, confirm it, then pause, change or stop it.

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.

Ask for an endpoint

You should see a 201 with "state": "running" and an id.

FieldWhat it is
requestWhat you want to know, 3 to 2,000 characters. Required
gateway_idWhich camera. Leave it out to let Dialect choose among those you may use
time_zoneIANA name, used when you ask about schedules or “today”
titleThe 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

endingMeans
proposedIt worked. proposal holds what waits for a person
no_cameraNo gateway you may use could look
not_in_viewThe thing isn’t in the camera’s view
cant_read_sureIt found the thing, but couldn’t read it sure enough to propose
already_existsAn endpoint already answers this
not_by_lookingA camera can’t answer this
no_answer_fits, answers_splitThe answers it tried didn’t fit, or disagreed
stoppedSomeone stopped it
step_limit, time_limitIt ran out of room. Ask again, more narrowly
refusedThe request couldn’t be taken
interrupted, internal_error, unexplainedSomething 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.

Write a draft
Test a draft, then propose it

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

KeyRules
nameLowercase letters, digits and underscores, starting with a letter, 2 to 40 characters. Not test, versions or frames
titleOne line, 1 to 80 characters
gateway_idThe gateway that reads it
fields1 to 20, by name. Field names start with a letter, up to 40 characters
every_sSeconds between checks, 2 to 3,600. Default 5
recordchanges (default) keeps changes and unsure readings. all keeps every check
alertsUp to 20 rules. See Alerts

Choose its fields

typeKeysDefault bar
choicequestion, answers: 2 to 12, each answer’s name to what the photo shows0.9
yes_noquestion, yes, no: what the photo shows for each0.9
levelquestion, levels: 2 to 7, lowest first0.8
colourstates: 2 to 12, each name to a list of 1 to 8 RGB colours. margin defaults to 20
numbershows: digits or dial. question, unit, min, max. decimals (0 to 4) for digits. tolerance is required for a dial0.9 for digits
textquestion, max_length (1 to 200, default 60), pattern0.9
  • threshold may raise the bar, from 0.5 to 0.99, but not lower it below the default (bar_lowered).
  • A number outside min and max is reported unsure. It’s never clamped.
  • A pattern can’t use backreferences or lookaround.
  • Answer names can’t be none_of_these, unknown, unavailable, not_in_view or covered. Those aren’t answers: Dialect reports them as missing.
  • asks is the question shown to people, 3 to 80 characters. It doesn’t change the reading.

Every field says where to read:

KeyWhat it is
targetwhat 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
regionA fixed spot, as x, y, w, h fractions of the frame
anchorA 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.

Define a flashing light

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.

RouteDoes
POST /v1/endpoints/versions/{id}/declineDeclines a proposal. Agents may do this
POST /v1/endpoints/versions/{id}/reopenUndoes 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}/versionsEvery version of a name
GET /v1/needsEverything 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_s or 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} with purpose or log_schedule changes 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

RouteDoes
POST /v1/endpoints/{name}/pauseThe 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}/resumeStarts checking again
POST /v1/endpoints/{name}/stopEnds 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.

Set a log schedule

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.

Next steps