DEVELOPERS

The Mātr API

Everything Translation Studio does is one HTTP call. Send English text and a target language; get back the model's own translation, the corrected one, and the structural reasons for the change. Same engine, same quota, same 2,000+ languages.

API access is included in Professional. Create keys on your account page.

Authentication

Every request carries a key in the Authorization header. Keys start with matr_live_, are shown once when created, and can be revoked individually from the account page. A key inherits the plan of the account that owns it, so it stops working if the subscription lapses.

Authorization: Bearer matr_live_...

Keys can translate and read your history and glossary. They cannot change the plan, create other keys, or delete the account, so a leaked key can at worst spend your quota until you revoke it.

Base URL: https://api.matrintelligence.com. All bodies are JSON, UTF-8.

Quick start

curl:

curl https://api.matrintelligence.com/v1/translate \
  -H "Authorization: Bearer matr_live_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "The doctor told my mother to rest for two days.",
       "target_language": "sinhala"}'

Python:

import requests

r = requests.post(
    "https://api.matrintelligence.com/v1/translate",
    headers={"Authorization": "Bearer matr_live_..."},
    json={"text": "The doctor told my mother to rest for two days.",
          "target_language": "sinhala"},
    timeout=90,
)
r.raise_for_status()
result = r.json()
print(result["corrected"])          # the corrected translation
print(result["changed"])            # True if the correction differed from the model's pick
print(result["usage"]["used"], "of", result["usage"]["limit"], "characters this period")

Node:

const r = await fetch("https://api.matrintelligence.com/v1/translate", {
  method: "POST",
  headers: {
    Authorization: "Bearer matr_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "The doctor told my mother to rest for two days.",
    target_language: "sinhala",
  }),
});
if (!r.ok) throw new Error((await r.json()).error);
const { corrected, changed, divergence_top } = await r.json();

POST /v1/translate

Request fields:

Field	Meaning
`text`	English source text. Up to 5,000 characters per request on Professional; whitespace at the ends is ignored.
`target_language`	A language key from `GET /v1/languages`, such as `sinhala` or `basque`.
`deep`	Optional, default false. Scores 12 candidates instead of 8. Counts twice against the character quota.
`alpha`	Optional, default 0.5. Correction strength as the weight on the model's own score: 0.3 is the strongest correction, 0.7 the lightest. Values outside 0.3 to 0.7 are clamped.

Response:

{
  "baseline": "...",            // the model's own best candidate
  "corrected": "...",           // the candidate Mātr selected
  "changed": true,              // whether the two differ
  "original_rank": 3,           // where the corrected candidate ranked before scoring
  "scores": {"model": 0.61, "umf": 0.74, "final": 0.68},
  "divergence_top": [           // the structural dimensions that mattered most
    {"dimension": "word_order", "value": 1.0},
    {"dimension": "case_marking", "value": 0.85}
  ],
  "deep": false,
  "history_id": "…",            // retrievable via GET /v1/history/{id}
  "usage": {"chars_billed": 48, "used": 1290, "limit": 1000000,
            "resets_at": "2026-10-01T00:00:00Z"}
}

Characters are billed only when a translation is returned. A failed call costs nothing. Terms in your glossary are applied automatically.

GET /v1/languages

Public, no key required. Returns every target language the engine serves, with the key to pass as target_language, the display name, the native name where we have it, and the ISO 639-3 code.

{"languages": [{"key": "basque", "name": "Basque", "native_name": "", "code": "eus"}, ...],
 "count": 2331}

History and glossary

Endpoint	What it does
`GET /v1/me`	Your plan, limits, and usage for the current period.
`GET /v1/history?limit=20&offset=0`	Past translations, newest first. Professional retains them without limit.
`GET /v1/history/{id}`	One translation in full, including both texts and scores.
`GET /v1/glossary`	Your required term translations.
`POST /v1/glossary`	Add a term: `{"source_term": "...", "target_term": "..."}`. Up to 200 terms.
`DELETE /v1/glossary/{id}`	Remove a term.

Errors

Errors are JSON with an error code you can branch on, and an HTTP status that says which kind of problem it is.

Status and code	Meaning
401 `auth_required`, `invalid_api_key`	No key, or a key that is unknown or revoked.
402 `payment_failed`, `subscription_required`	The subscription needs attention on the account page before the key works again.
403 `api_access_required`	The account's current plan does not include the API.
422 `empty_text`, `text_too_long`, `invalid_language`	The request itself. `text_too_long` includes `max_chars`; `invalid_language` includes the allowed keys.
429 `rate_limit`, `quota_exceeded`	Too many requests this minute, or the period's characters are used up. `quota_exceeded` includes `used`, `limit` and `resets_at`.
502 `backend_error`	The engine could not complete the request. Nothing was billed; retry with backoff.

Limits

Professional	Value
Characters per month	1,000,000 (deep requests count twice)
Characters per request	5,000
Requests per minute	20, per account
Keys per account	10
Request timeout to allow	Up to 90 seconds; deep requests take longer than standard ones

Need more volume, other source languages, or a deployment in your own environment? Talk to us.