API & MCP
Dialecto’s programmatic surface is deliberately small — three endpoints, each with its own credential. There are no outbound webhooks today: Dialecto doesn’t push events to your systems; it receives scans, serves tools, and listens to GitHub.
The scan API
POST /api/repos/:repo_id/scans and
GET /api/repos/:repo_id/scan-config, authenticated with the per-repo
scan token. Full contract in Scanning & CI.
The MCP server
POST /mcp speaks the Model Context Protocol (JSON-RPC 2.0;
initialize, tools/list, tools/call), so your editor or coding
agent can drive the same surgical, review-gated flow the web editor
uses — with the same permission checks.
Authentication is a per-user API token
(Authorization: Bearer …), valid for 365 days and stored only as a
hash. Every tool call re-checks the acting user’s actual permissions
server-side — an agent can do exactly what its human could, no more.
Make your token in your account settings, under Agent access: it lasts
365 days, is shown once, and a new one replaces the old. On a self-hosted
server the operator can also mint one with mix dialecto.mcp.token you@example.com.
The tools
| Tool | Needs | Does |
|---|---|---|
list_untranslated |
view | list a locale’s untranslated entries (up to 500) |
stage_translation |
edit (locale-scoped) | stage one translation — a string, or N plural forms |
preview_diff |
view | the minimal unified diff of staged changes |
discard_change |
edit | drop one entry’s staged change |
open_pr |
open-PR | open the PR for the approved staged batch |
get_voice_card |
view | the brand-voice card for a locale — accepts a persona |
Note the shape: an agent stages translations; it does not merge
them. open_pr ships only the approved batch, and the PR itself is
still yours to review on GitHub. Tool errors come back as structured
MCP errors, not stack traces.
The GitHub webhook (inbound)
POST /webhooks/github receives the GitHub App’s deliveries —
push events that bring in your translation files, pull-request events
that re-run the gate checks, and installation and repository events.
Every delivery is verified against the webhook
secret (HMAC-SHA256 over the raw body, constant-time compared) before
anything is processed. This endpoint is for GitHub, not for you — but
it’s documented so your security review doesn’t have to guess.
Rate limits
Scan uploads and /mcp calls are each limited to 30 requests per
minute per client IP address; exceeding that returns 429 with a
retry-after header. The GitHub webhook is not rate-limited, because
GitHub does not redeliver a throttled delivery, and its signature check is
what authenticates it. Login and signup endpoints have their own tighter
budgets.