API reference

GET /v1/health#

Liveness (no data)

Authentication: None (public)

Success response (200)

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/health"

GET /v1/openapi.json#

This document

Authentication: None (public)

Success response (200)

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/openapi.json"

GET /v1/sites#

List sites

Authentication: Secret API key · Required scope: sites:read

Parameters

Success response (200)

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/sites" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

POST /v1/sites#

Create a site

Authentication: Secret API key · Required scope: sites:write

Parameters

Request body

Success response (201)

Response example

{
  "id": "3f2b1c9e-6a4d-4c8e-9a53-0d2f7b1e8c11",
  "siteKey": "rl_site_live_abcdefghijklmnopqrstuv",
  "name": "My shop",
  "sourceLanguage": "en",
  "targetLanguages": [
    "fr",
    "de"
  ],
  "allowedOrigins": [
    "https://shop.example.com"
  ]
}

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/sites" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","sourceLanguage":"string","targetLanguages":["string"],"allowedOrigins":["string"]}'

GET /v1/sites/{siteId}#

Get a site

Authentication: Secret API key · Required scope: sites:read

Parameters

Success response (200)

Response example

{
  "id": "3f2b1c9e-6a4d-4c8e-9a53-0d2f7b1e8c11",
  "siteKey": "rl_site_live_abcdefghijklmnopqrstuv",
  "name": "My shop",
  "sourceLanguage": "en",
  "targetLanguages": [
    "fr",
    "de"
  ],
  "allowedOrigins": [
    "https://shop.example.com"
  ]
}

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/sites/${SITE_ID}" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

PATCH /v1/sites/{siteId}#

Update site settings

Authentication: Secret API key · Required scope: sites:write

Parameters

Request body

Success response (200)

Response example

{
  "id": "3f2b1c9e-6a4d-4c8e-9a53-0d2f7b1e8c11",
  "siteKey": "rl_site_live_abcdefghijklmnopqrstuv",
  "name": "My shop",
  "sourceLanguage": "en",
  "targetLanguages": [
    "fr",
    "de"
  ],
  "allowedOrigins": [
    "https://shop.example.com"
  ]
}

Status codes

Example

curl -sS -X PATCH "$RL_API_BASE/v1/sites/${SITE_ID}" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","targetLanguages":["string"],"allowedOrigins":["string"]}'

POST /v1/sites/{siteId}/strings#

Submit extracted strings (max 1000)

Up to 1000 items. The response lists the key of every item in order; identical text (after normalisation) yields the same key and is stored once.

Authentication: Secret API key · Required scope: strings:write

Parameters

Request body

Success response (200)

Response example

{
  "items": [
    {
      "key": "0123456789abcdef",
      "kind": "text"
    },
    {
      "key": "fedcba9876543210",
      "kind": "attr"
    }
  ],
  "stored": 2
}

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/sites/${SITE_ID}/strings" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"text":"string"}]}'

POST /v1/sites/{siteId}/scan#

Start a crawl (async job)

Every URL and the sitemap URL must be on one of the site's allowedOrigins and pass the SSRF check. Returns a job.

Authentication: Secret API key · Required scope: sites:write

Parameters

Request body

Success response (202)

Response example

{
  "id": "9b1e6c52-2f43-4a8e-8d0b-5c7a1f3e9a20",
  "kind": "publish",
  "siteId": "3f2b1c9e-6a4d-4c8e-9a53-0d2f7b1e8c11",
  "state": "succeeded",
  "attempts": 1,
  "progressPercent": 100,
  "createdAt": "2026-10-28T12:00:00Z",
  "finishedAt": "2026-10-28T12:00:09Z",
  "result": {
    "version": 7,
    "publishedAt": "2026-10-28T12:00:09Z",
    "targets": [
      {
        "target": "r2-primary",
        "ok": true
      },
      {
        "target": "cdn-secondary",
        "ok": true
      }
    ]
  }
}

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/sites/${SITE_ID}/scan" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["string"],"sitemapUrl":"string","respectRobots":true}'

POST /v1/sites/{siteId}/translate#

Machine-translate missing strings (async job)

Enqueues one job per target language (or per requested language). Never overwrites reviewed or manual translations.

Authentication: Secret API key · Required scope: translations:write

Parameters

Request body

Success response (202)

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/sites/${SITE_ID}/translate" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"langs":["string"],"keys":["string"],"force":true}'

POST /v1/sites/{siteId}/publish#

Build and publish bundles (async job)

Builds and publishes signed bundles to every storage target. Poll the job; a succeeded job's `result.version` is the published version.

Authentication: Secret API key · Required scope: bundles:publish

Parameters

Request body

Success response (202)

Response example

{
  "id": "9b1e6c52-2f43-4a8e-8d0b-5c7a1f3e9a20",
  "kind": "publish",
  "siteId": "3f2b1c9e-6a4d-4c8e-9a53-0d2f7b1e8c11",
  "state": "succeeded",
  "attempts": 1,
  "progressPercent": 100,
  "createdAt": "2026-10-28T12:00:00Z",
  "finishedAt": "2026-10-28T12:00:09Z",
  "result": {
    "version": 7,
    "publishedAt": "2026-10-28T12:00:09Z",
    "targets": [
      {
        "target": "r2-primary",
        "ok": true
      },
      {
        "target": "cdn-secondary",
        "ok": true
      }
    ]
  }
}

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/sites/${SITE_ID}/publish" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"onlyIfChanged":true}'

GET /v1/jobs/{jobId}#

Job status

Status of a job created by scan, translate or publish. Succeeded publish jobs include result.version, publishedAt and per-target results.

Authentication: Secret API key

Parameters

Success response (200)

Response example

{
  "id": "9b1e6c52-2f43-4a8e-8d0b-5c7a1f3e9a20",
  "kind": "publish",
  "siteId": "3f2b1c9e-6a4d-4c8e-9a53-0d2f7b1e8c11",
  "state": "succeeded",
  "attempts": 1,
  "progressPercent": 100,
  "createdAt": "2026-10-28T12:00:00Z",
  "finishedAt": "2026-10-28T12:00:09Z",
  "result": {
    "version": 7,
    "publishedAt": "2026-10-28T12:00:09Z",
    "targets": [
      {
        "target": "r2-primary",
        "ok": true
      },
      {
        "target": "cdn-secondary",
        "ok": true
      }
    ]
  }
}

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/jobs/${JOB_ID}" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

GET /v1/sites/{siteId}/translations#

List translations

Authentication: Secret API key · Required scope: translations:read

Parameters

Success response (200)

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/sites/${SITE_ID}/translations" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

PUT /v1/sites/{siteId}/translations/{lang}/{key}#

Manual override

Authentication: Secret API key · Required scope: translations:write

Parameters

Request body

Success response (200)

Status codes

Example

curl -sS -X PUT "$RL_API_BASE/v1/sites/${SITE_ID}/translations/${LANG}/${KEY}" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"string"}'

GET /v1/sites/{siteId}/glossary#

Get glossary

Authentication: Secret API key · Required scope: translations:read

Parameters

Success response (200)

Response example

{
  "doNotTranslate": [
    "Acme"
  ],
  "preferred": [
    {
      "source": "cart",
      "lang": "fr",
      "target": "panier"
    }
  ]
}

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/sites/${SITE_ID}/glossary" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

PUT /v1/sites/{siteId}/glossary#

Replace glossary

Authentication: Secret API key · Required scope: translations:write

Parameters

Request body

Success response (200)

Response example

{
  "doNotTranslate": [
    "Acme"
  ],
  "preferred": [
    {
      "source": "cart",
      "lang": "fr",
      "target": "panier"
    }
  ]
}

Status codes

Example

curl -sS -X PUT "$RL_API_BASE/v1/sites/${SITE_ID}/glossary" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"doNotTranslate":["string"],"preferred":[{"source":"string","target":"string"}]}'

GET /v1/sites/{siteId}/export#

Full export (format=json|xliff|xliff2|po|pot|csv|tmx, optional lang)

Returns every translation of the site in the chosen format so a customer can keep or edit them elsewhere. Never cached. Formats that hold one language per file (po, xliff2) return a .zip when several languages are included.

Authentication: Secret API key · Required scope: translations:read

Parameters

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/sites/${SITE_ID}/export" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

POST /v1/sites/{siteId}/import#

Import translations from a file (multipart) or the JSON export (application/json)

Send multipart/form-data with field `file` (and `reference` for key-based formats such as android, messages-json and keyvalue-json), plus optional fields `format` (auto-detected when omitted), `lang` (for single-language files that do not state one), `status` (machine|reviewed|manual: overrides every entry's status; default: the file's own status, else manual) and `dryRun` (true = report the plan, write nothing). Strings the site does not know are skipped and listed in `issues`. Entries whose inline tags or placeholders do not survive are rejected. Any error-level issue rejects the whole import (422).

Authentication: Secret API key · Required scope: translations:write

Parameters

Request body

Success response (200)

Response example

{
  "formatId": "xliff",
  "dryRun": false,
  "applied": true,
  "planned": 1,
  "written": 1,
  "skippedProtected": 0,
  "stats": {
    "unitsRead": 2,
    "matched": 1,
    "skippedUntranslated": 0,
    "skippedUnknown": 1,
    "skippedInvalid": 0,
    "conflicts": 0
  },
  "issues": [
    {
      "severity": "warning",
      "code": "unknown-string",
      "message": "String not found on this site; skipped.",
      "where": "trans-unit b"
    }
  ]
}

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/sites/${SITE_ID}/import" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file":"string","reference":"string","format":"json","lang":"string","status":"machine","dryRun":true}'

GET /v1/sites/{siteId}/usage#

Strings, characters, engine cost

Authentication: Secret API key · Required scope: usage:read

Parameters

Success response (200)

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/sites/${SITE_ID}/usage" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

GET /v1/usage/quota#

Plan allowance and period usage for the key's tenant

The plan allowance and where the tenant stands in the current period (404 when quotas are not enabled on the deployment).

Authentication: Secret API key · Required scope: usage:read

Success response (200)

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/usage/quota" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

GET /v1/keys#

List secret keys (never returns secrets)

Authentication: Secret API key · Required scope: keys:manage

Parameters

Success response (200)

Status codes

Example

curl -sS -X GET "$RL_API_BASE/v1/keys" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

POST /v1/keys#

Create a secret key (secret shown once)

The secret is returned once in this response and never again. The new key cannot hold scopes the calling key lacks. Test keys cannot create keys. Responses are never replayed from an Idempotency-Key.

Authentication: Secret API key · Required scope: keys:manage

Parameters

Request body

Success response (201)

Response example

{
  "id": "c2a4f0de-7b61-4e3a-9f55-1a8b2c3d4e5f",
  "name": "CI",
  "prefix": "rl_sec_live_",
  "kind": "secret",
  "scopes": [
    "strings:write",
    "bundles:publish"
  ],
  "secret": "rl_sec_live_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/keys" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","scopes":["sites:read"],"siteId":"00000000-0000-0000-0000-000000000000","expiresAt":"2026-01-01T00:00:00Z"}'

POST /v1/keys/{id}/rotate#

Rotate a key (new valid now, old valid for a grace period)

The new key works immediately; the old key keeps working for gracePeriodSeconds (default 24 h, max 30 days).

Authentication: Secret API key · Required scope: keys:manage

Parameters

Request body

Success response (201)

Response example

{
  "id": "c2a4f0de-7b61-4e3a-9f55-1a8b2c3d4e5f",
  "name": "CI",
  "prefix": "rl_sec_live_",
  "kind": "secret",
  "scopes": [
    "strings:write",
    "bundles:publish"
  ],
  "secret": "rl_sec_live_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/keys/${ID}/rotate" \
  -H "Authorization: Bearer $RL_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gracePeriodSeconds":1}'

DELETE /v1/keys/{id}#

Revoke a key

Authentication: Secret API key · Required scope: keys:manage

Parameters

Status codes

Example

curl -sS -X DELETE "$RL_API_BASE/v1/keys/${ID}" \
  -H "Authorization: Bearer $RL_SECRET_KEY"

POST /v1/discover#

Browser snippet reports untranslated strings (site key + allowed Origin; off by default)

Disabled unless the deployment enables it (404). Authenticated by the public site key plus the browser's Origin header, which must be on the site's allowedOrigins.

Authentication: None (public)

Parameters

Request body

Success response (202)

Status codes

Example

curl -sS -X POST "$RL_API_BASE/v1/discover" \
  -H "Content-Type: application/json" \
  -d '{"siteKey":"string","items":[{"text":"string"}]}'