amaGama API¶

amaGama answers HTTP requests with JSON. The API lives under /api/v1/; /tmserver/ is the older path to the same read API and still works.

TM suggestion request¶

Request TM suggestions with a GET of <SERVER>/api/v1/<SOURCE_LANGUAGE>/<TARGET_LANGUAGE>/unit/<QUERY>, where:

Placeholder	Description
<SERVER>	The URL of the amaGama server
<SOURCE_LANGUAGE>	Source language code: de, en, en_GB
<TARGET_LANGUAGE>	Target language: ar, es_AR, fr, hi
<QUERY>	The URL escaped string to be queried

Note

<SOURCE_LANGUAGE> and <TARGET_LANGUAGE> should be language codes in the form of LANG OR LANG_COUNTRY. LANG should be a language code from ISO 639 and COUNTRY a country code from ISO 3166. The following are valid examples: ar, de, en, en_GB, es_AR, fr, gl, hi, tlh,… For the public server the code en is used for the source language for most of the FOSS localization files, not en_US.

For example:

https://amagama-live.translatehouse.org/api/v1/en/af/unit/Computer

The string can also be passed as source in the query string, which avoids problems with / in the string on some web servers:

https://amagama-live.translatehouse.org/api/v1/en/af/unit/?source=Open%2FSave

Providing options¶

It is possible to provide some options in the request URL by using a query string with one or more of the following fields.

Option	Description
min_similarity	The minimum similarity between the string to be searched and the strings to match. See Levenshtein distance. Values below 70 are raised to 70. Default: `MIN_SIMILARITY` (70).
max_candidates	The maximum number of results, at most 30. Default: `MAX_CANDIDATES` (5).
style	The project’s checker style, so that accelerators and similar markup are matched as that project writes them (`&` for KDE, `_` for GNOME). One of: creativecommons, drupal, gnome, ios, kde, libreoffice, minimal, mozilla, openoffice, reduced, standard, terminology, wx.
exclude	Comma-separated globs of block names to leave out, such as `hosted-*`. A suggestion stays while any of its sources is left.
only	Comma-separated globs of the block names to keep, such as `gnome-*,kde`. Suggestions with no recorded source are left out.
weight	Comma-separated `glob:weight` pairs, weights from 0 to 10, such as `gnome-:1.5,hosted-:0.5`. Suggestions are ordered by quality times the best weight of their sources: each source’s first matching glob, else the block’s default `weight` in the sources list. `quality` itself isn’t changed.
licence	Comma-separated globs of the SPDX licence identifiers to keep, such as `GPL-,MIT`, or with `!` to leave out, such as `!AGPL-`: see Choosing by licence.
jsoncallback	Wrap the reply in a call to this JavaScript function (JSONP).

The source options are applied before max_candidates, and a suggestion’s sources lists only the sources it keeps. Of equally good suggestions, the one more of its kept sources supplied comes first.

For example:

https://amagama-live.translatehouse.org/api/v1/en/af/unit/File?style=gnome&max_candidates=10
https://amagama-live.translatehouse.org/api/v1/en/af/unit/File?exclude=hosted-*&weight=gnome-*:1.5

Choosing by licence¶

licence lists the licences a client can use its suggestions under, as globs of SPDX identifiers (case doesn’t matter). Each source’s licence is an SPDX expression, and a source is kept when the expression can be met with the listed licences alone:

A OR B lets you choose either licence, so one of them listed is enough.
A AND B applies both licences, so both must be listed.
A WITH exception only adds permissions to A, so A listed is enough.

With licence=GPL-*,MIT:

Source’s licence	Kept	Because
`GPL-2.0-or-later`	yes	GPL-* matches it
`LGPL-2.1-or-later`	no	a glob matches the whole identifier: GPL-* isn’t LGPL
`LGPL-2.1-or-later OR GPL-3.0-only`	yes	you can use it under GPL-3.0-only
`MIT AND Apache-2.0`	no	Apache-2.0 also applies, and isn’t listed
`MIT AND (Apache-2.0 OR GPL-2.0-only)`	yes	MIT, and GPL-2.0-only for the choice
`GPL-2.0-or-later WITH Classpath-exception-2.0`	yes	GPL-* matches the licence

A glob starting with ! leaves licences out: a licence is allowed when it matches a listed glob and no ! one. With only ! globs, every other licence is allowed. With licence=!AGPL-*:

Source’s licence	Kept	Because
`MIT`	yes	every licence but AGPL is allowed
`AGPL-3.0-only`	no	AGPL-* is left out
`MIT OR AGPL-3.0-only`	yes	you can use it under MIT
`MIT AND AGPL-3.0-only`	no	AGPL-3.0-only also applies

licence=GPL-*,!GPL-3.0-* keeps GPL-2.0-only but not GPL-3.0-only.

Sources with no known licence, or files under different licences, are left out. A suggestion stays while any of its sources is kept, as with only.

A request returns 404 if the source language isn’t in the database or if no string is given. It returns 400 if the source and target languages are the same (en_US is the same as en, en_GB isn’t) or if a weight isn’t glob:weight. Replies may be cached for an hour (Cache-Control: max-age=3600, public).

TM suggestion results¶

The results from a TM suggestion request are provided in JSON format. It is a list containing zero or more results. The results contain the following fields:

Field	Description
source	Matching unit’s source language text
target	Matching unit’s target language text
quality	A Levenshtein distance measure of quality as percent
rank	An internal quantity that might disappear. Ignore.
sources	The blocks whose imports supplied this translation, in alphabetical order: `api` for the write API. Empty if none was recorded.

An example:

[
  {
    "source": "Computer",
    "quality": 100.0,
    "target": "Rekenaar",
    "rank": 100.0,
    "sources": ["gnome-51", "kde"]
  },
  {
    "source": "Computers",
     "quality": 88.888888888888886,
     "target": "Rekenaars",
     "rank": 100.0,
     "sources": ["kde"]
   },
   {
     "source": "&Computer",
     "quality": 88.888888888888886,
     "target": "Rekenaar",
     "rank": 100.0,
     "sources": ["libreoffice-26.8"]
   },
   {
     "source": "_Computer",
     "quality": 88.888888888888886,
     "target": "_Rekenaar",
     "rank": 100.0,
     "sources": ["gnome-51"]
   },
   {
     "source": "My Computer",
     "quality": 72.727272727272734,
     "target": "My Rekenaar",
     "rank": 100.0,
     "sources": ["legacy-2019"]
   }
 ]

Available languages¶

GET <SERVER>/api/v1/languages/ lists the languages in the database:

{
  "sourceLanguages": ["en"],
  "targetLanguages": ["af", "ar", "de"]
}

Sources¶

GET <SERVER>/api/v1/sources/ lists the blocks the translations were imported from, one entry per block and source language. The names are those suggestions give in sources. Titles are in the language ?lang= asks for, or else the best of Accept-Language, among the translated ones; otherwise English. The reply gives that language as lang and its text direction (ltr or rtl) as dir.

Field	Description
name	The block’s name
title	Its title, or its name if it has none
version	Its release, such as `"51"`, or null
displayTitle	The title with its release, worded for the language
licence	Its SPDX licence expression, or null
sourceLanguage	The source language
targetLanguages	The target languages it was imported for
units	How many units its files gave, before those already there from other files were merged
imported	When it was last imported, in UTC
weight	Its default `weight` in lookups: 1 unless the server sets one

{
  "lang": "en",
  "dir": "ltr",
  "sources": [
    {
      "name": "gnome-51",
      "title": "GNOME",
      "version": "51",
      "displayTitle": "GNOME 51",
      "licence": "GPL-2.0-or-later",
      "sourceLanguage": "en",
      "targetLanguages": ["af", "ar", "de"],
      "units": 5000,
      "weight": 1.0,
      "imported": "2026-10-25T12:00:00Z"
    }
  ]
}

Adding translations¶

When ENABLE_DATA_ALTERING_API is on (it is off by default), the API also accepts translations. style can be passed as for lookups.

Method	Path	Body
PUT or POST	`/api/v1/<SRC>/<TGT>/unit/<QUERY>`	JSON object with `source` and `target`
POST	`/api/v1/<SRC>/<TGT>/store/<NAME>`	JSON list of objects with `source` and `target`
PUT	`/api/v1/<SRC>/<TGT>/store/<NAME>`	A translation file; its format is taken from `<NAME>`

The store requests reply added <N> units from <NAME>. A request with a language code that isn’t valid returns 400. Strings too long for the database’s index are skipped. Each request is recorded as an import of block api, named unit or <NAME>.