Public API

The read-only, API-key-authenticated surface your applications call to fetch translations — both endpoints, with exact response shapes.

The Public API is the small, stable surface your application calls at runtime or build time. It lives under https://langsync.api.norcube.com/api/v1/ and is authenticated exclusively with API keys — user-session tokens don't work here, and API keys don't work on the rest of the API.

It is read-only by design: two GET endpoints, no writes, no AI calls. A leaked key can read your translations but can't change anything.

Authentication

Authorization: Apikey <your-api-key>

Bearer <your-api-key> is accepted as an alias. Anything else — or a revoked key — returns 401 UNAUTHORIZED. The key determines the organization; the namespace in the path must belong to it.

`GET /api/v1/namespaces/{namespaceName}/languages`

Lists the languages attached to a namespace. Use it to populate a language picker or to discover the numeric IDs the translations endpoint needs.

[
  {
    "id": 68,
    "code": "en",
    "name": "English",
    "isDefault": true,
    "isFallback": false,
    "isCustom": false
  },
  {
    "id": 31,
    "code": "de",
    "name": "German",
    "isDefault": false,
    "isFallback": false,
    "isCustom": false
  }
]

Field	Meaning
`id`	The numeric language ID — pass this as `langId` below. Stable; safe to cache or hard-code.
`code`	The language code.
`name`	Display name.
`isDefault`	Whether this is the namespace's default (source) language.
`isCustom`	Whether it's a custom language of your organization.
`isFallback`	Reserved; currently always `false`.

`GET /api/v1/namespaces/{namespaceName}/terms/translations?langId={id}`

Returns every translated term in the namespace for one language.

{
  "meta": { "timestamp": "2026-07-10T12:00:00Z" },
  "cursors": {},
  "list": [
    { "mark": "welcome.title", "value": "Willkommen" },
    { "mark": "button.submit", "value": "Absenden" }
  ]
}

Behaviour to build around:

langId is the numeric language ID, not the code. Always pass it explicitly — when omitted, the endpoint falls back to LangSync's built-in English language, which is rarely what you want.
Only terms with a stored translation in that language appear. Untranslated terms are absent from list, not empty. Handle fallback to your default language in your i18n layer.
Explicitly empty translations (saved as "") do appear, with an empty value.
The response is a single complete list — the meta/cursors envelope is shared with the rest of the platform, but you don't need to paginate here.

What's not here

Writes. Creating or editing terms happens in the dashboard, the CLI, or the dashboard API with a session token.
AI translation. Triggered from the dashboard, CLI, or dashboard API — never by runtime keys.
Cross-namespace listing. The API is namespace-scoped; enumerate the namespaces you ship in your own config.

Caching

Translations change on human timescales. Cache responses aggressively — in memory with a TTL, or fetch at build time and ship static files (see Fetch translations for both patterns). The endpoints don't currently emit validator headers (ETag / Last-Modified), so use time-based expiry rather than conditional requests.

Errors

Status	`type`	When
401	`UNAUTHORIZED`	Missing, malformed, or revoked key — or the namespace doesn't exist in the key's organization.
500	`INTERNAL_ERROR`	Transient server error; retry with backoff.

Body shape and the full platform code list: Limits and errors.