API & MCP

Dialecto’s programmatic surface is deliberately small — three endpoints, each with its own credential, each rate-limited. 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. Tokens are currently minted by an operator on the server (mix dialecto.mcp.token you@example.com); in-app token management is a planned follow-on.

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 — pull-request events that re-run the gate checks, and installation lifecycle 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

API endpoints are rate-limited per client IP and path (the scan API and /mcp share a 30-requests-per-minute budget); exceeding it returns 429 with a retry-after header. Login and signup endpoints have their own tighter budgets.