REST API

Base URL, tokens, errors, limits and the main routes.

Call Dialect from any program over HTTPS with a bearer token. This page covers what holds across routes, and the full reference is at api.dialectlayer.com/docs, with the schema at api.dialectlayer.com/openapi.json.

Use this base URL
https://api.dialectlayer.com

Routes sit under /v1. Times are Unix seconds, unless a field says otherwise.

Authenticate a request

Check who a token is

You should see who the token is: role, workspace_id, read_only, reaches, and payment, which is null once the workspace has paid.

Create a token

An administrator issues tokens in the console: Access, then Grant access, then An agent’s token. Each starts dialect_pat_ and is shown once.

ChoiceOptions
RoleAgent reads and proposes endpoints. Operator works in the console
AccessFull, or Read only: reads endpoints, their history and notes, and subscribes to changes
GatewaysAll, or the ones you choose
Workspace administratorOperators only. Can grant and revoke access, invite gateways and confirm endpoints
ExpiresNever, in 30 or 90 days, in a year, or on a date

Rotate or revoke a token on Access. A rotated token keeps working for 24 hours beside its replacement. Manage tokens, gateways and invitations in the console. The routes behind them aren’t part of this API and can change. Treat an administrator’s token like its owner’s password, since it can grant access.

Handle errors

Errors answer with a status and a JSON body.

Response when a limit is reached
  • detail is a sentence to show or log.
  • code is what to branch on when present. Every 401 and 422 has one. Others may not, so fall back to the status.
  • retry_at says when a limit lifts, and Retry-After carries the wait.
  • pay_url, manage_url, contact and needs_person appear when only a person can lift a refusal.
  • 422 validation errors have the same shape, detail naming the first problem and code: "invalid".

Every response has an X-Request-Id. Quote it if you write to us.

StatuscodeMeans
401unauthorizedThe token is missing, mistyped or revoked. An administrator issues one in the console: Access, then Grant access, then An agent’s token
401token_expiredIt expired. Ask an administrator to rotate it
401token_rotatedIt was replaced. Use the new one
402payment_requiredNeeds a paid plan. A person must pay
403read_onlyA read-only token tried to change something
403forbiddenThe token’s role can’t do this
404not_confirmedThe endpoint waits for a person to confirm it
409busyA setup is already running
409name_takenThat name is in use
409more_things_needed, quote_neededThe plan doesn’t cover another endpoint
409supersededA newer version took its place
413noneThe request is over 12 MB
422invalidThe request isn’t valid
422purpose_missingA new endpoint needs a purpose
422bar_loweredA threshold is below the field’s default
429rate_limited, daily_limitWait until retry_at
500unexpectedOur fault. Quote request_id

Each route in the reference lists the statuses it can answer.

Retry safely

Send an Idempotency-Key on any POST, PUT or PATCH, up to 255 characters. A repeat returns the first answer with Idempotent-Replayed: true and does nothing twice.

  • Keys are your token’s own, and kept for 24 hours.
  • The same key with a different request answers 422 idempotency_key_reused.
  • The same key while the first is running answers 409 idempotency_in_progress.
  • Answers of 5xx aren’t kept, so you can retry those.

Stay within limits

LimitAmount
Photos and locating30 a minute per token
Endpoint tests100 a day per workspace
Proposals20 a day
Setups50 a day, one at a time
Endpoints per gateway50
Endpoints per plan10, then talk to us
Fields per endpoint20
Alert rules per endpoint20
Webhooks per person or token10
Webhook tests20 an hour per webhook
Request body12 MB

Find a route

Read values

RouteDoes
GET /v1/endpointsEvery endpoint and its values
GET /v1/endpoints/{name}One endpoint’s current values
GET /v1/endpoints/{name}/schemaThe JSON Schema of its values
GET /v1/endpoints/{name}/historyIts changes
GET /v1/endpoints/{name}/summaryHow long and how often, over a window
GET /v1/endpoint-changesChanges across all endpoints
GET /v1/pictures/{id}A kept picture

Set up endpoints

RouteDoes
GET /v1/sensesYour gateways and whether each can look
POST /v1/senses/{id}/lookA photo now. size=small or full
POST /v1/senses/{id}/locateFind up to 5 things in view
POST /v1/setup-runsAsk for an endpoint
GET /v1/setup-runs/{id}/statusHow that’s going
POST /v1/endpoints/testTest a draft
POST /v1/endpointsPropose a draft
POST /v1/endpoints/versions/{id}/confirmConfirm, as an administrator
GET /v1/needsWhat waits for a person

Run endpoints

RouteDoes
PATCH /v1/endpoints/{name}Change its purpose or log_schedule
POST /v1/endpoints/{name}/pause, /resume, /stopPause, resume or stop it
GET, PUT /v1/endpoints/{name}/alertsIts alert rules
GET /v1/alertsAlerts
POST /v1/alerts/{id}/handlingClaim one
GET, POST /v1/endpoints/{name}/webhooksIts webhooks
GET /v1/endpoints/{name}/logIts scheduled log

Keep notes

GET /v1/notes?search= and PUT /v1/notes/{key} keep short notes for later, up to 4,000 characters each, such as what a camera’s view holds. A workspace can have 500.

Next steps