API reference

Three endpoints. Real documentation.

The Interscript REST API runs at https://interscript.org/api. Open source, no auth, no rate limits (yet). Browse the OpenAPI 3.1 spec below or download it from /openapi.json.

↓ OpenAPI 3.1 JSON Postman collection ↗

POST /api/transliterate

Transliterate a single string. Use POST when the input is large, contains newlines, or you prefer explicit request bodies.

Request body

{
  "system": "bgnpcgn-ukr-Cyrl-Latn-2019",
  "input": "Антон",
  "stage": "main"           // optional, defaults to "main"
}

Response — 200 OK

{
  "system": "bgnpcgn-ukr-Cyrl-Latn-2019",
  "input": "Антон",
  "output": "Anton",
  "stage": "main",
  "durationMs": 7
}

cURL

curl -X POST 'https://interscript.org/api/transliterate' \
  -H 'Content-Type: application/json' \
  -d '{"system":"bgnpcgn-ukr-Cyrl-Latn-2019","input":"Антон"}'

JavaScript (browser / Node 18+)

const res = await fetch("https://interscript.org/api/transliterate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    system: "bgnpcgn-ukr-Cyrl-Latn-2019",
    input: "Антон",
  }),
})
const { output } = await res.json()
console.log(output) // → "Anton"

Ruby

require "net/http"
require "json"

uri = URI("https://interscript.org/api/transliterate")
res = Net::HTTP.post(
  uri,
  { system: "bgnpcgn-ukr-Cyrl-Latn-2019", input: "Антон" }.to_json,
  "Content-Type" => "application/json",
)
puts JSON.parse(res.body)["output"]  # → "Anton"

GET /api/transliterate

Same operation, query-string form. Easier to test in a browser or one-liner curl. Avoid for inputs containing newlines.

Query parameters

Name	Required	Description
`system`	yes	Interscript system code
`input`	yes	Source text (≤ 10,000 chars)
`stage`	no	Stage to execute (default `main`)

cURL

curl -G 'https://interscript.org/api/transliterate' \\
  --data-urlencode 'system=bgnpcgn-ukr-Cyrl-Latn-2019' \\
  --data-urlencode 'input=Антон'

GET /api/systems

List every transliteration system in the catalogue. Optional filters by authority or script.

Query parameters

Name	Required	Description
`authority`	no	Authority slug (`bgnpcgn`, `iso`, …)
`source_script`	no	ISO 15924 source code (`Cyrl`, `Arab`, …)
`destination_script`	no	ISO 15924 destination code

Example response (truncated)

{
  "count": 287,
  "systems": [
    {
      "code": "bgnpcgn-amh-Ethi-Latn-1967",
      "authority": "bgnpcgn",
      "source_script": "Ethi",
      "destination_script": "Latn",
      "name": "Romanization of Amharic (1967)",
      "year": "1967"
    },
    …
  ]
}

GET /api/detect

Given a source-script input and an observed romanization, returns the candidate systems in the relevant script family. Pair with the detection playground for full ranking.

Query parameters

Name	Required	Description
`input`	yes	Source text
`output`	yes	Observed romanization
`source_script`	no	Narrow the candidate set

Schemas

Response shapes (subset shown — see full spec for components/schemas/*).

TransliterationResult

{
  "type": "object",
  "required": ["system", "input", "output", "stage", "durationMs"],
  "properties": {
    "system": { "type": "string" },
    "input":  { "type": "string" },
    "output": { "type": "string" },
    "stage":  { "type": "string" },
    "durationMs": { "type": "number" }
  }
}

Limits & fairness

Input size: 10,000 chars per request.
Auth: none. CORS open to all origins.
Rate limits: currently none. If abused, will add a per-IP cap with 429 responses and Retry-After headers.
Uptime: best-effort. For production pipelines, run interscript-ts locally — same engine, same byte-for-byte output.
Privacy: no logging of input content. Aggregate request counts only.