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.
https://api.dialectlayer.comRoutes sit under /v1. Times are Unix seconds, unless a field says otherwise.
Authenticate a request
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.
| Choice | Options |
|---|---|
| Role | Agent reads and proposes endpoints. Operator works in the console |
| Access | Full, or Read only: reads endpoints, their history and notes, and subscribes to changes |
| Gateways | All, or the ones you choose |
| Workspace administrator | Operators only. Can grant and revoke access, invite gateways and confirm endpoints |
| Expires | Never, 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.
detailis a sentence to show or log.codeis what to branch on when present. Every 401 and 422 has one. Others may not, so fall back to the status.retry_atsays when a limit lifts, andRetry-Aftercarries the wait.pay_url,manage_url,contactandneeds_personappear when only a person can lift a refusal.- 422 validation errors have the same shape,
detailnaming the first problem andcode: "invalid".
Every response has an X-Request-Id. Quote it if you write to us.
| Status | code | Means |
|---|---|---|
| 401 | unauthorized | The token is missing, mistyped or revoked. An administrator issues one in the console: Access, then Grant access, then An agent’s token |
| 401 | token_expired | It expired. Ask an administrator to rotate it |
| 401 | token_rotated | It was replaced. Use the new one |
| 402 | payment_required | Needs a paid plan. A person must pay |
| 403 | read_only | A read-only token tried to change something |
| 403 | forbidden | The token’s role can’t do this |
| 404 | not_confirmed | The endpoint waits for a person to confirm it |
| 409 | busy | A setup is already running |
| 409 | name_taken | That name is in use |
| 409 | more_things_needed, quote_needed | The plan doesn’t cover another endpoint |
| 409 | superseded | A newer version took its place |
| 413 | none | The request is over 12 MB |
| 422 | invalid | The request isn’t valid |
| 422 | purpose_missing | A new endpoint needs a purpose |
| 422 | bar_lowered | A threshold is below the field’s default |
| 429 | rate_limited, daily_limit | Wait until retry_at |
| 500 | unexpected | Our 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
| Limit | Amount |
|---|---|
| Photos and locating | 30 a minute per token |
| Endpoint tests | 100 a day per workspace |
| Proposals | 20 a day |
| Setups | 50 a day, one at a time |
| Endpoints per gateway | 50 |
| Endpoints per plan | 10, then talk to us |
| Fields per endpoint | 20 |
| Alert rules per endpoint | 20 |
| Webhooks per person or token | 10 |
| Webhook tests | 20 an hour per webhook |
| Request body | 12 MB |
Find a route
Read values
| Route | Does |
|---|---|
GET /v1/endpoints | Every endpoint and its values |
GET /v1/endpoints/{name} | One endpoint’s current values |
GET /v1/endpoints/{name}/schema | The JSON Schema of its values |
GET /v1/endpoints/{name}/history | Its changes |
GET /v1/endpoints/{name}/summary | How long and how often, over a window |
GET /v1/endpoint-changes | Changes across all endpoints |
GET /v1/pictures/{id} | A kept picture |
Set up endpoints
| Route | Does |
|---|---|
GET /v1/senses | Your gateways and whether each can look |
POST /v1/senses/{id}/look | A photo now. size=small or full |
POST /v1/senses/{id}/locate | Find up to 5 things in view |
POST /v1/setup-runs | Ask for an endpoint |
GET /v1/setup-runs/{id}/status | How that’s going |
POST /v1/endpoints/test | Test a draft |
POST /v1/endpoints | Propose a draft |
POST /v1/endpoints/versions/{id}/confirm | Confirm, as an administrator |
GET /v1/needs | What waits for a person |
Run endpoints
| Route | Does |
|---|---|
PATCH /v1/endpoints/{name} | Change its purpose or log_schedule |
POST /v1/endpoints/{name}/pause, /resume, /stop | Pause, resume or stop it |
GET, PUT /v1/endpoints/{name}/alerts | Its alert rules |
GET /v1/alerts | Alerts |
POST /v1/alerts/{id}/handling | Claim one |
GET, POST /v1/endpoints/{name}/webhooks | Its webhooks |
GET /v1/endpoints/{name}/log | Its 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.