Workflow and recovery guide
The compact guide packaged with every API V2 build, written for AI agents and automation.
The production API origin is https://api.lingohub.com. If these files describe another environment, use the origin in the servers entry of the OpenAPI contract instead. All paths begin with /v2.
Start with the operation index. Each group links to the complete OpenAPI contract, which is authoritative for request fields, required/nullable properties, public enum values, filters and responses. The deployed API describes itself at GET /v2/openapi.json (with an API token) and at the public /public/api-docs/v2.
Getting started
Section titled “Getting started”Create an API key in your workspace’s API access settings, or ask a workspace administrator for one. Give it only the workspace and stack permissions your integration needs. Changes to workspace owners are not available in V2. Supply the key using LINGOHUB_API_KEY; do not paste it into reports or commit it to a profile file.
With the CLI installed, verify your key and its effective access first:
lingohub --json api call getApiKeylingohub --json api call getWorkspacelingohub api operationsThe CLI calls https://api.lingohub.com unless --base-url or LINGOHUB_BASE_URL selects another origin; set one of them before running these commands against any other environment. The operation inventory is offline; the first two commands call the API. Use api mcp-tools --operation OPERATION to inspect the bundled method/path/input schema before a new workflow. Select real IDs from list/read responses, and compare the CLI’s bundled contract with the deployed GET /v2/openapi.json before relying on a new capability.
For content transfer, upload using the documented createImport multipart operation, inspect getImport and its entries, submit createExport, and inspect getExport before downloading. An accepted job can still fail or partially commit. Keep recorded IDs so a client interruption does not require resubmitting the mutation. Shared segment edits affect every usage; inspect usages before editing.
A file workflow with the CLI
Section titled “A file workflow with the CLI”Set LINGOHUB_API_KEY first. The following variables are placeholders for public IDs returned by the API, not sample IDs to submit. en.json is your own supported source file and IMPORT_INTENT/EXPORT_INTENT are unique values you retain for these two intended submissions.
lingohub --json api call listProjects --query limit=20lingohub --json api call getProject --path projectId="$PROJECT_ID"lingohub --json api call listResources --path branchId="$BRANCH_ID" --query limit=20lingohub --json --include-headers api upload createImport \ --path branchId="$BRANCH_ID" --upload en.json --form language_code=en \ --idempotency-key "$IMPORT_INTENT"# Read IMPORT_ID from the accepted response, then inspect completion and entries.lingohub --json api wait getImport --path importId="$IMPORT_ID" --timeout 300lingohub --json api call listImportEntries --path importId="$IMPORT_ID" --query limit=20lingohub --json --include-headers api call createExport \ --path branchId="$BRANCH_ID" --field 'language_codes=["en"]' \ --idempotency-key "$EXPORT_INTENT"# Read EXPORT_ID from the accepted response. Download to a new destination file.lingohub --json api wait getExport --path exportId="$EXPORT_ID" --timeout 300lingohub --json api download-export "$EXPORT_ID" --output exported-resources.zipChoose the branch from getProject/listBranches; do not assume every project has the same branch identity. A timeout stops polling, not the backend job. Reuse api wait with the recorded job ID. Inspect all pages of entries after a partial or failed result before deciding what needs correction. Continue each list using --query cursor="$NEXT_CURSOR" and unchanged parent/filter/limit until has_more is false. Download links expire; the download command obtains a fresh permitted link and never overwrites the destination.
For a conditional metadata change, GET the resource with headers first. Copy the complete quoted ETag into SEGMENT_ETAG, then send only the intended fields:
lingohub --json --include-headers api call getSegment --path segmentId="$SEGMENT_ID"lingohub --json api call updateSegment --path segmentId="$SEGMENT_ID" \ --if-match "$SEGMENT_ETAG" --field 'description="Label on the sign-in button"'This description is shared across the segment’s usages. Use listSegmentKeys to discover them. A 412 requires a fresh read and a deliberate decision, not an automatic overwrite. JSON field values need JSON quoting; shell quoting alone does not make a string a JSON value.
Beta compatibility
Section titled “Beta compatibility”While V2 is in beta, changes can include renamed operations and fields, tightened input constraints, changed responses and removed operations. The beta has no compatibility or deprecation guarantee.
Keep the CLI up to date: its operation inventory and MCP tools are generated from the contract bundled with it, and it is updated together with the API. Operations added after your CLI was built need a newer CLI before you can call them by name. The raw-request command remains available, but it does not check compatibility. If you call the HTTP API directly, keep the OpenAPI contract your integration was built against and compare it with the deployed GET /v2/openapi.json to find changes.
Authentication and identity
Section titled “Authentication and identity”Send an API token as Authorization: Bearer <token>. Browser sessions do not authenticate V2. Use getApiKey to discover the current key’s scope and effective permissions. Self-managed keys follow their owner’s live permissions subject to the shared cap: billing/subscription is at most VIEW and workspace management is NO_ACCESS, including for workspace owners. Current key lifecycle, workspace policy, user permissions and stack scope can change between requests.
Use public IDs from responses. Never construct IDs from database numbers or use V1 friendly IDs. Shared segment text edits affect every usage; occurrence key changes apply to the selected file occurrence. Inspect usages before changing shared content. Membership endpoints keep workspace/stack owners protected.
Constructing requests
Section titled “Constructing requests”Use the exact fields and enum values in OpenAPI. Unknown fields/query parameters, duplicate JSON keys and scalar coercion are rejected. Omitted, null, empty and false have distinct meanings. PATCH uses JSON merge-patch; absent fields remain unchanged, and null clears only nullable fields. PUT replaces a complete subresource at its known key. Do not send a body to bodyless actions.
Ordinary resource lists use limit, cursor, has_more and next_cursor. Keep filters and sort order identical while following a cursor. Stop when has_more is false. Use each operation’s documented filter schema; filters are not shared indiscriminately across resource groups. Do not infer total counts from a page.
Filters
Section titled “Filters”filter is URL-encoded JSON: where holds exactly one _and or _or with an array of clauses, and sort lists fields prefixed with + (ascending) or - (descending). A clause is a nested _and/_or or one field with one operator. Fields are named <object_type>[<field>] after the list’s items.
Filter operators
Section titled “Filter operators”A clause compares one field with one operator: { "<field>": { "<operator>": <value> } }.
| Operator | Matches items whose field | Value |
|---|---|---|
_eq, _ne |
equals / does not equal the value | one value |
_in, _nin |
is one of / none of the values | non-empty array |
_lt, _lte, _gt, _gte |
is less than / at most / greater than / at least the value | number or timestamp |
_within |
lies between the two bounds, both included | [lower, upper] |
_contains, _ncontains |
contains / does not contain the text, case-sensitive | text |
_icontains, _nicontains |
contains / does not contain the text, ignoring case | text |
_starts, _ends |
starts / ends with the text, case-sensitive | text |
_like, _nlike |
matches / does not match a pattern, case-sensitive: % stands for any text, _ for one character |
text |
_ilike, _nilike |
like _like and _nlike, ignoring case |
text |
_blank, _nblank |
has no text (missing or empty) / has text | true |
_null, _nnull |
has no value / has a value | true |
_true, _false |
is true / is false | true |
Which operators a field offers depends on its type:
| Field type | Operators |
|---|---|
| text | _eq _ne _contains _ncontains _icontains _nicontains _starts _ends _like _nlike _ilike _nilike _blank _nblank |
| id, enum | _eq _ne _in _nin |
| integer | _eq _ne _in _nin _lt _lte _gt _gte _within _null _nnull |
| timestamp | _eq _lt _lte _gt _gte _within _null _nnull |
| boolean | _true _false |
Values have the form the responses show: public ids (stack_0197c8f2-…), enum values (STANDARD_JSON), and timestamps in RFC 3339 UTC (2026-01-01T00:00:00Z). Each list operation shows its own fields in a table under its filter parameter in the API reference: the field name, its type, the operators it offers and whether it can sort.
More clauses:
{ "project[type]": { "_in": ["STANDARD_JSON", "I18NEXT_JSON"] } }{ "import[created_at]": { "_within": ["2026-11-01T00:00:00Z", "2026-11-30T23:59:59Z"] } }{ "invitation[accepted_at]": { "_null": true } }{ "branch[is_default]": { "_false": true } }{ "key[key]": { "_like": "checkout.%" } }Conditional writes and retries
Section titled “Conditional writes and retries”For supported writes, GET the specific resource, preserve its opaque strong ETag, then send If-Match. A 412 means the representation changed; reread and decide whether to apply the intended change. Unsupported operations reject If-Match. PUT responses omit ETag; GET again for the current validator. ETags provide write preconditions, not a general conditional-GET cache protocol.
Use one Idempotency-Key for each intended POST operation. Retained successful ordinary results can replay after current authorization. This protection is best effort: loss or expiry of the retained result and the gap between committing an operation and retaining its result prevent an exactly-once guarantee. Never blindly retry an uncertain mutation with a new key. Inspect the affected resource after idempotency_outcome_unknown or a lost response. A idempotency_key_in_use response supplies Retry-After while another execution is active. Reusing a key for a different request is rejected.
One-time signing-secret rotation cannot replay the secret; retained same-key requests report an unknown outcome. If its response is lost, inspect metadata and deliberately rotate again when appropriate. Do not log tokens, signing secrets or complete authorization headers.
Asynchronous work and errors
Section titled “Asynchronous work and errors”Creation can acknowledge a resource before its background work is complete. Follow the operation’s resource/job identity, poll the documented status and inspect terminal errors and entries. Do not infer success from an accepted request or a download URL alone. Branch initialization must succeed before operations that require ready content. Backups/restores use the documented point-in-time semantics; no branch-merge operation is implied.
Errors are RFC 9457 Problem Details with a machine-readable code, request correlation and optional field errors. Preserve the response status, code, pointer and request ID when reporting a failure. Invisible resources can return 404. Respect rate-limit headers and Retry-After; rate limiting does not authorize retrying an uncertain mutation. Bulk operations may return per-item failures; inspect every result.
Backup and restore scope
Section titled “Backup and restore scope”A backup captures branch content using the existing snapshot format. created_at is the scheduling time, not the exact capture instant. Inspect getBackup and wait for SUCCEEDED before using it with createBackupRestore; poll getBackupRestore for the separate restore outcome. The source backup and destination branch must belong to the same project and have compatible source languages.
Choose language_codes with the following consequences in mind:
| Selection | Existing behavior |
|---|---|
| Target languages only | Restore those languages on existing keys. Preserve current source text, key metadata/labels and added keys. Missing keys are not recreated. A deleted file can be recreated empty; include the source language if its keys must be restored. |
| Source language included | Restore captured source keys and metadata/labels. Recreate missing keys and remove keys added since the snapshot inside backed-up files; removal affects the occurrence in every language, even unselected target languages. |
| Unselected target languages | Preserve their current texts on surviving keys. This does not protect an occurrence removed by a source-inclusive restore. |
Files added after the snapshot remain. Surviving files keep their current target export path; a recreated file uses its captured path when the snapshot contains one. Backup/restore does not roll back project settings, workflows, images, comments or history to the capture time. SUCCEEDED means the restore completed this scope; it does not promise that a target-only restore recovered deleted keys. These are current shared restore semantics, not a new V2 overwrite policy.
Automatic schedules use getBackupSettings and setBackupSettings: replace a complete UTC schedule and a nonempty branch selection in the same project. DAILY uses period and time; WEEKLY also requires day_of_week. Use the current GET ETag for a conditional replacement. deleteBackupSettings disables future scheduling; retained backups and already queued work remain.
Invitation assignment discovery
Section titled “Invitation assignment discovery”getInvitationStackAssignment reads a retained email invitation’s stored requested assignment. NOT_CONFIGURED means there is no stored assignment; UNAVAILABLE means its complete details cannot currently be shown. Only AVAILABLE carries the current public role and ordered stack IDs plus stored language defaults. Null and an empty language map retain their distinction. The caller needs workspace members-view permission and settings-management permission on every referenced stack to see those details. Never treat this response as effective access or proof that the invitation was accepted. It creates or changes no assignment and does not permit owner changes.
Project settings
Section titled “Project settings”getProjectSettings returns every setting of a project in one resource: export and import defaults, file-format options, key normalisation, placeholder recognition and, for a project with an integration, the integration settings. updateProjectSettings changes any of them as a JSON merge-patch: send only the sections and fields that change, also inside the sections of format. Lists are replaced as a whole, and null removes a format section; a section that doesn’t exist yet needs all its required fields. All changes are applied together or not at all; one 422 lists every invalid field. Equal values write nothing. Use the GET ETag for If-Match; the PATCH response carries the next one. To go back to the default placeholders, send placeholders.default_definitions as placeholders.definitions. Changes don’t rewrite job-specific overrides; already queued jobs without overrides use the new defaults.
Reference files
Section titled “Reference files”The API serves this guide and its reference files at /public/api-v2/: llms.txt, guide.md, openapi.json and one page per operation group. They describe the contract of the deployed build, not the permissions of a particular key. Error type URLs under /errors/ are public documentation pages. The CLI also serves the operations as MCP tools over stdio (lingohub api mcp-serve).
Import changes
Section titled “Import changes”After checking import status and entry outcomes, use listImportChanges to see what the import changed: one item per segment and file, with the key change and the text changes in each language you can read. Follow next_cursor with the same filter; current ancestry, key access and readable languages apply on every page. segment_id and key_id turn null once the segment or key is deleted; names, paths and contents stay. Changes may grow during processing and can be filtered by access, so an empty page does not prove an unchanged import. The list does not preview or replay an import and does not change retention policy.
Disconnecting Git
Section titled “Disconnecting Git”deleteProjectGitIntegration removes a project’s stored connection, bindings, filters and schedules. GET its configuration first and optionally send the complete response’s ETag as If-Match. Success is an empty 204. Project content, shared authentication and retained jobs remain; remote webhook cleanup is best effort and this operation does not cancel in-flight work. A stale validator is 412, a concurrent authentication rebind is 409 conflict requiring a fresh read, and a missing or already disconnected integration is 404. Current stack settings-management access is required.
Glossaries, terms and forms
Section titled “Glossaries, terms and forms”Glossaries contain typed terms with independently addressable forms. Translatable forms name a language; untranslatable forms do not. A language has at most one preferred form, and inherited languages reuse a preferred form rather than appearing as independent forms. Use each returned public identity and the published schemas. A form mutation invalidates the complete parent term validator too, so GET the term again before a subsequent conditional update or deletion. The last form is removed by deleting its term. Creation replay and conditional writes retain the general limits described above; several requests do not become one atomic transaction.
For retained public API request metadata, use listApiLogs and getApiLog. Every key reads its own retained requests; workspace API-access view permits other keys’ requests in that workspace, while stack-scoped keys remain restricted to their own. Permission and retention changes apply to subsequent requests. The response exposes public IDs, method/path/status and time, not request bodies or authorization headers. Keep the same filter/sort when following cursors; filter to the path of interest because log reads can themselves create log traffic. Invisible or expired detail entries return resource_not_found.
Style guides use createStyleGuide / listStyleGuides / getStyleGuide / updateStyleGuide / deleteStyleGuide. Nested global-rule PATCH fields merge; a null individual rule resets to NOT_SPECIFIED, while the rules object cannot be null. Per-language setStyleGuideLanguageRules replaces overrides and clears omitted fields; setStyleGuideLanguageVariant requires a regional variant of the addressed general language. GET each known-key resource for its validator after PUT, whose response carries no ETag. Per-language edits also change the parent style-guide validator. Current permissions and workspace visibility apply throughout.
Provider setup discovery
Section titled “Provider setup discovery”CodeCommit repository and branch discovery returns one native provider page. Omit limit; continue with the opaque next_cursor and the same authentication/repository until has_more=false. Repository pages can contain up to 1,000 items. Branch commit/protection metadata and repository URLs remain null when not supplied by the provider. Native calls preserve the page unchanged; they do not automatically follow it.
Azure repository discovery requires organization and project_key (ID or name from project discovery). It returns the complete selected project’s list. GitHub, Azure and CodeCommit directory discovery requires a full immutable commit_sha and returns direct children of path (empty for root). Azure requires repository_namespace=organization/project; CodeCommit has no namespace. Use getCodeCommitBranch with repository_name and git_branch to obtain a selected branch head, then pass that immutable commit_sha to directory discovery. Branch names containing slashes remain query values. Use listAzureOrganizations to discover the organization before listing its projects; a known organization is also accepted directly.
These complete-list endpoints reject cursor and limit. Upstream bodies are bounded to 2 MiB; complete lists allow up to 1,000 items, except GitHub Contents, where 1,000 results cannot prove completeness and the accepted maximum is 999. Success has has_more=false and next_cursor=null. Oversized, truncated, continued or non-directory results fail with 502 upstream_error. Use a narrower directory or known repository/path selection when browsing cannot complete. No stored discovery snapshot or file download is created. Azure Items uses isSymLink to distinguish symbolic links from ordinary blob files. Ordinary-file format/language hints are path-only suggestions, not validation of contents or source-language choice.
Project moves and detachment
Section titled “Project moves and detachment”moveProject queues POST /v2/projects/{projectId}/move with a destination stack_id;
the project keeps its own segments, equal texts are not merged. Automations belong to
the stack: a moved project runs the destination’s, and a detached project’s new stack
starts with a copy of the shared stack’s. detachProject queues
POST /v2/projects/{projectId}/detach without a body. Both return a PROJECT_MOVE
job and a Location for getProjectMove; poll until the status is terminal. A
queued request cancels with MOVE_SOURCE_CHANGED when its source has changed.
Use an Idempotency-Key to recover a lost response while retry protection remains
available. A move status is retained with the existing synchronization record; it
is not a permanent move history. Inspect the project before resubmitting an
uncertain request.
The shared workflow is preserved: missing memberships (including owners), language permissions and workspace-key grants are copied; existing destination assignments win. Members/keys may thereby gain access to other destination projects. A private source stack is removed; a private destination is promoted to shared. Moving from a shared stack requires a shared destination. Detachment makes a new private stack, copying shared content for the detached project. Exact-segment deduplication is opt-in; document occurrences are not deduplicated.
Moves require settings management on the source project and destination stack;
detachment and status reads require settings management on the project. API-key
stack scope stays unchanged: a key can lose project/status access after the move,
even if the operation succeeded. stack_id in the move response always means the
project’s current stack, including after subsequent moves. A scheduling audit records
accepted intent and the requesting actor; it is not proof of completion.