API reference
The two API surfaces, authentication schemes, and the conventions every LangSync endpoint follows.
LangSync has two API surfaces on the same host
(https://langsync.api.norcube.com):
- The dashboard API — everything the dashboard and the CLI do: namespaces, terms, translations, glossary, sync jobs, custom prompts, API keys, audit log, migrators. Authenticated with short-lived user-session tokens.
- The Public API — a minimal, stable,
read-only surface under
/api/v1/for fetching translations from your applications. Authenticated with API keys.
The authoritative endpoint reference is the live Swagger UI served
by the LangSync service at /swagger/ — the dashboard calls the same
API for every action, so the spec is always current.
Endpoint paths can change on the dashboard API. Treat the Swagger spec as the source of truth; this section documents the conventions and the stable public surface.
Authentication
Two schemes, both via the Authorization header:
| Scheme | Surface | Notes |
|---|---|---|
Bearer <JWT> | Dashboard API | Short-lived org-scoped session token. The dashboard and CLI manage these automatically; for manual integration, mint tokens via the auth service — see Platform → Tokens. |
Apikey <key> | Public API | Long-lived application credential — see API keys. Bearer <key> is also accepted with the same value. |
Resource groups (dashboard API)
- Namespaces — CRUD, plus language attach/detach per namespace.
- Terms — CRUD, per-language translation upserts, single-cell AI recommendation, bulk import (upload → precheck → finish).
- Translations — bare-text AI translation (manual translation) and custom prompt CRUD.
- Sync jobs — enqueue (
202+ job ID) and poll; see Sync jobs. - Glossary — the org glossary, its languages, items, and item translations.
- Languages — list shared + custom; create/delete custom languages.
- API keys — list / create / revoke.
- Audit log — filtered reads plus a distinct-actors listing; see Audit log.
- Migrators — POEditor project listing and bulk migration.
Conventions
Pagination
List endpoints use cursor pagination: pass limit and cursor
query parameters; responses carry a cursors.next value to pass back,
absent/empty when you've reached the end. Limits are clamped
server-side (terms: max 100 per page; audit log: max 200).
Asynchronous work
Operations that can take long — sync jobs, bulk imports, batch auto-translate — return immediately and continue in the background. Sync jobs and imports expose their state for polling; batch translation completion is signalled by email.
Errors
Every error body has the same two fields:
{
"type": "NOT_FOUND",
"msg": "The requested resource was not found."
}type is the programmatic identifier, msg the human-readable detail.
The HTTP status matches the category. See
Limits and errors for the codes and
rate limits.
Regenerating typed clients
Norcube's own consumers generate their clients from the service's
Swagger spec (the frontend via swagger-typescript-api, the CLI via
oapi-codegen). If you want a typed client in your stack, pull
/swagger/api_swagger.json from the service host into your generator
of choice.