The Mātr API

Every call on this page except GET /v1/languages carries a key in the Authorization header. A key is matr_live_ followed by 40 hexadecimal characters. It is shown once, when it is created, and can be revoked on its own from the account page. A key inherits the plan of the account that owns it, so it stops working if the subscription lapses or the plan no longer includes the API.

Authorization: Bearer matr_live_...

Keys can translate, read the account's email address, plan and usage, read your history, and read and change your glossary. They cannot create or revoke keys, change the plan, or export or delete the account: those need you signed in on this website. So a leaked key cannot take the account over, but until you revoke it, it can spend your quota, see the account's email address, read your translations and change your glossary.

Call the API from your own server, never from a web page, where the key would be visible to anyone who opens it.

Base URL: https://api.matrintelligence.com. Bodies are JSON in UTF-8, apart from some error answers (see Errors).

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=170,  # a translation can take up to 160 seconds (see Limits)
)
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) {
  // Not every error is JSON (see Errors): read the code only from a JSON body.
  const json = (r.headers.get("content-type") ?? "").includes("application/json");
  const body = json ? await r.json() : {};
  throw new Error(`${r.status} ${body.error ?? r.statusText}`);
}
const { corrected, changed, divergence_top } = await r.json();

Request fields:

Response:

{
  "baseline": "...",            // the model's first translation, before correction
  "corrected": "...",           // the translation Mātr chose
  "changed": true,              // whether it chose a different translation
  "original_rank": 3,           // its rank among the model's candidates (1 is first)
  "scores": {"model": 0.61, "umf": 0.74, "final": 0.68},
  "divergence_top": [           // where the language differs most from English
    {"dimension": "word_order", "value": 1.0},
    {"dimension": "case_marking", "value": 0.85}
  ],
  "deep": false,
  "history_id": "…",            // for GET /v1/history/{translation_id}
  "usage": {"chars_billed": 47, "used": 1290, "limit": 1000000,
            "resets_at": "2026-10-29T09:30:00.000000Z"}   // when the allowance resets
}

Characters are counted only for translations that succeed: a refused or failed call costs nothing. When the text contains terms from your glossary, the engine is asked to use their translations, up to ten terms a translation.

Public, no key required. Returns every target language the engine serves, by English name: the key to pass as target_language, the English name, the native name, and the ISO code where the engine knows one. The native name may be empty, and the code empty or left out.

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

A refusal from the API is JSON with a stable error code you can branch on, sometimes with details beside it, and an HTTP status that says which kind of problem it is. The codes it sends to a key:

Some answers carry no error:

• 422 with a detail list: a body or parameter that does not match the schema. 400 with a detail message: a body that is not UTF-8 text.
• HTML pages from the server in front of the API: 413 for a body over 2 MB, 502 when the API cannot be reached (while it restarts, for example), 503 for more than about ten requests a second from one address, and 504 when an answer takes more than 170 seconds.

So branch on the status first: a 502, 503 or 504 from the server in front of the API may be HTML, not JSON.

GET /v1/me shows the plan's limits, the period's usage, and when the period resets.

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