# Workflow and recovery guide

The compact guide packaged with every API V2 build, written for AI agents and automation.

> **Generated from the API**
>
> This page is the guide that every API V2 build serves at [https://api.lingohub.com/public/api-v2/guide.md](https://api.lingohub.com/public/api-v2/guide.md), published here after each release. It is compact on purpose: AI agents and scripts read it. The other API V2 guides explain the same rules step by step.

> **Beta**
>
> API V2 is in beta. Endpoints, request and response fields, and behavior can still change. Use the LingoHub CLI (`lingohub`) where possible: it is updated together with the API. If you call the HTTP API directly, be prepared to update your integration when V2 changes. See "Beta compatibility" below.

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](https://api.lingohub.com/public/api-v2/openapi.json) instead. All paths begin with `/v2`.

Start with [the operation index](https://api.lingohub.com/public/api-v2/llms.txt). Each group links to the complete [OpenAPI contract](https://api.lingohub.com/public/api-v2/openapi.json), 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

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:

```sh
lingohub --json api call getApiKey
lingohub --json api call getWorkspace
lingohub api operations
```

The 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

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.

```sh
lingohub --json api call listProjects --query limit=20
lingohub --json api call getProject --path projectId="$PROJECT_ID"
lingohub --json api call listResources --path branchId="$BRANCH_ID" --query limit=20
lingohub --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 300
lingohub --json api call listImportEntries --path importId="$IMPORT_ID" --query limit=20
lingohub --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 300
lingohub --json api download-export "$EXPORT_ID" --output exported-resources.zip
```

Choose 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:

```sh
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

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

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

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

`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

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:

```json
{ "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

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

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

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

`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

`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

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

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

`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

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

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

`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.
