# LingoHub Developers

> Guides, recipes and the API reference for LingoHub, a translation management platform: API V2 (Beta) for new integrations, API V1 for existing ones, and the CDN API for loading translations into running apps.

Every link below is a Markdown copy of a page. Any page of this site is also available as Markdown: append `.md` to its URL, or request it with `Accept: text/markdown`.

## Before the first request

- Use API V2 for new work. It is in beta: endpoints and fields can still change. API V1 is stable and limited to projects, resource files, exports and repository pushes.
- API V2 is served at `https://api.lingohub.com/v2`; the paths in the reference include the `/v2` prefix. Authenticate with `Authorization: Bearer <API key>`. A key belongs to one workspace and starts with `lh-api_`. The CDN API uses a separate CDN key and `https://cdn.lingohub.com`.
- Objects are identified by public IDs from API responses, such as `pr_0197c8f2-…`. Never construct an ID.
- Lists are paged with `limit` and `cursor`: repeat the request with `cursor` set to `next_cursor` until `has_more` is false, and keep `filter` and sort unchanged.
- Send an `Idempotency-Key` with every `POST`, and retry with the same key. Change existing objects with `If-Match` set to the `ETag` of your last read; on `412`, read again.
- Imports and exports are asynchronous jobs: a `202` response names the job; poll it until its status is final, then read its entries.
- Errors are RFC 9457 problem details with a machine-readable `code`. On `429`, wait the seconds in `Retry-After`.
- A segment is a source text with its translations and is shared by every key that shows it; a key is where a segment appears in one file. Changing a segment changes it everywhere.
- From a terminal or as MCP tools, prefer the LingoHub CLI (`lingohub`): it is updated together with API V2.

## Guides: Getting started
- [Introduction](https://developers.lingohub.com/docs/introduction.md): What you can build with LingoHub's APIs and which one to use.
- [Concepts](https://developers.lingohub.com/docs/concepts.md): How LingoHub organizes translations: workspaces, stacks, projects, branches, files, keys, segments and texts.
- [API keys](https://developers.lingohub.com/docs/api-keys.md): Create a key, choose its permissions and send it with every request.
- [LingoHub CLI](https://developers.lingohub.com/docs/cli.md): Install the lingohub command, sign in through the browser and use API V2 from your terminal, scripts and AI agents.
- [Use LingoHub with AI agents](https://developers.lingohub.com/docs/ai-agents.md): Give Claude Code, Cursor, Codex and other AI agents access to LingoHub: as MCP tools, through the LingoHub CLI, or with the API and these docs as Markdown.

## Guides: API V2 (Beta)
- [API V2 (Beta) overview](https://developers.lingohub.com/docs/api-v2-overview.md): Programmatic access to workspaces, projects, files, texts, glossaries and automation.
- [Pagination and filtering](https://developers.lingohub.com/docs/api-v2-pagination-and-filtering.md): Page through lists with cursors and select items with filters.
- [Errors and rate limits](https://developers.lingohub.com/docs/api-v2-errors-and-rate-limits.md): The error format, the error code catalog and the rate limit headers.
- [Safe retries and conditional updates](https://developers.lingohub.com/docs/api-v2-safe-retries.md): Retry writes with idempotency keys and update safely with ETags.
- [Imports and exports](https://developers.lingohub.com/docs/api-v2-imports-and-exports.md): Upload files and download translations as asynchronous jobs.
- [Webhooks](https://developers.lingohub.com/docs/api-v2-webhooks.md): Receive LingoHub events at your own endpoint and verify their signatures.
- [Workflow and recovery guide](https://developers.lingohub.com/docs/api-v2-workflow-guide.md): The compact guide packaged with every API V2 build: request rules, the file workflow with the CLI, and what to do when a request is uncertain. Written for AI agents and automation.

## Guides: API V1
- [API V1 overview](https://developers.lingohub.com/docs/api-v1-overview.md): The stable API for projects, resource files, exports and repository pushes: base URL, authentication, URLs and conventions.
- [Errors and status codes](https://developers.lingohub.com/docs/http-status-codes-error-messages.md): The status codes of API V1, the shapes of its error bodies and the rate limit headers.

## Guides: File formats
- [Supported file formats](https://developers.lingohub.com/docs/file-types.md): Every file format LingoHub imports and exports, with its file extensions, the project type to choose and whether plural forms are supported.
- [Android](https://developers.lingohub.com/docs/android.md): Android string resources (strings.xml): LingoHub imports and exports string, string-array and plurals elements with their comments and format arguments.
- [Angular (angular-translate)](https://developers.lingohub.com/docs/angular.md): JSON files of angular-translate, a third-party library for AngularJS: LingoHub reads them like standard JSON files, with nested keys and comments.
- [Apple iOS strings](https://developers.lingohub.com/docs/apple-ios.md): Apple .strings and .stringsdict files for iOS and macOS: LingoHub imports and exports keys, comments, format specifiers and plural rules.
- [Xcode String Catalogs](https://developers.lingohub.com/docs/xcode-string-catalogs.md): Xcode String Catalog (.xcstrings) files: LingoHub imports and exports all languages of a catalog with plural, device and substitution variations, comments and states.
- [Flutter ARB](https://developers.lingohub.com/docs/flutter-arb.md): Application Resource Bundle (.arb) files of Flutter apps: LingoHub imports and exports the texts with their descriptions, placeholders and ICU plurals, and keeps the other attributes.
- [CSV](https://developers.lingohub.com/docs/csv.md): CSV files with one column per language: LingoHub imports and exports keys, descriptions, translations and their statuses, following RFC 4180.
- [Ember (ember-intl)](https://developers.lingohub.com/docs/ember-intl.md): JSON translation files of the third-party Ember.js libraries ember-intl and ember-i18n: LingoHub reads them with the JSON project type.
- [Gettext PO](https://developers.lingohub.com/docs/gettext-po.md): GNU gettext .po and .pot files: LingoHub imports and exports messages with their contexts, plural forms, comments and the file header.
- [Go i18n](https://developers.lingohub.com/docs/go-i18n.md): JSON files of version 1 of the go-i18n library: LingoHub imports and exports the id, translation and comment of every entry, including plural forms.
- [i18next](https://developers.lingohub.com/docs/i18next.md): JSON files of the i18next library: LingoHub imports and exports flat and nested keys, plural keys of JSON v3 and v4, interpolation placeholders and comments.
- [INI](https://developers.lingohub.com/docs/ini.md): INI files: LingoHub imports and exports key-value pairs, their sections and the comments directly above a key.
- [JSON](https://developers.lingohub.com/docs/json.md): JSON files of key-value pairs: LingoHub imports and exports flat and nested keys, arrays, plural objects, placeholders and comments.
- [Markdown](https://developers.lingohub.com/docs/markdown.md): Markdown files: LingoHub splits the content into paragraphs, headings, lists and code blocks, keeps the front matter and reads HTML comments as descriptions.
- [PHP define](https://developers.lingohub.com/docs/php.md): PHP files with define statements: LingoHub imports and exports the keys and values, printf placeholders and the comments above a statement.
- [Java properties](https://developers.lingohub.com/docs/properties.md): Java .properties files: LingoHub imports and exports key-value pairs with their comments, line continuations and ICU placeholders, in UTF-8 or with Unicode escapes.
- [Qt Linguist TS](https://developers.lingohub.com/docs/qt.md): Qt Linguist .ts files: LingoHub imports and exports messages with their contexts, comments, locations and %1 placeholders.
- [RESX and RESW](https://developers.lingohub.com/docs/reswresx.md): .resx and .resw files of .NET and Windows apps: LingoHub imports and exports the data entries with their values and comments.
- [Ruby on Rails YAML](https://developers.lingohub.com/docs/ruby-on-rails.md): YAML locale files of Ruby on Rails: LingoHub imports and exports nested keys, arrays, comments and %{name} placeholders, and reads the language from the first level.
- [SRT subtitles](https://developers.lingohub.com/docs/srt-subrip-subtitle.md): SubRip (.srt) subtitle files: LingoHub imports and exports the subtitle blocks and uses the timecode of a block as its key.
- [Symfony YAML](https://developers.lingohub.com/docs/symfony.md): YAML translation files of Symfony: LingoHub imports and exports flat and nested keys, arrays, comments and ICU placeholders.
- [Plain text](https://developers.lingohub.com/docs/text.md): Plain text (.txt) files: LingoHub splits the content into paragraphs and keeps the line breaks and the empty lines between them.
- [WebVTT subtitles](https://developers.lingohub.com/docs/vtt.md): WebVTT (.vtt) subtitle files: LingoHub imports and exports the cues, uses the timecode line as key, reads NOTE blocks as descriptions and keeps STYLE and REGION blocks.
- [XLIFF](https://developers.lingohub.com/docs/xliff.md): XLIFF 1.2 files: LingoHub imports and exports translation units with their notes, groups, states and inline placeholders. XLIFF 2 has a project type of its own.
- [LingoHints](https://developers.lingohub.com/docs/lingohints_introduction.md): LingoHints are annotations in the comments of a file that set the status, labels, quality check limits and the not-translatable flag when LingoHub imports the file.

## Guides: CDN SDKs
- [Apple (iOS) CDN SDK](https://github.com/lingohub/ios-cdn-sdk)
- [Android CDN SDK](https://github.com/lingohub/android-cdn-sdk)

## Recipes
- [Import a file (API V2)](https://developers.lingohub.com/recipes/import-a-file-api-v2.md): Upload a resource file to a project, wait for the import job and check the result of every file.
- [Export translations (API V2)](https://developers.lingohub.com/recipes/export-translations-api-v2.md): Request an export of a branch, wait for the job and download the file.
- [Update a translation safely (API V2)](https://developers.lingohub.com/recipes/update-a-translation-safely-api-v2.md): Find a key, read its segment with the German text and the ETag, and change the text only if nobody changed the segment in the meantime.
- [List with filters and cursors (API V2)](https://developers.lingohub.com/recipes/list-with-filters-and-cursors-api-v2.md): Select items with a filter, sort them, and read every page of a list.
- [Export translations (API V1)](https://developers.lingohub.com/recipes/exports.md): Request an export of a project, wait until it has finished and download the ZIP file.

## API reference
- [LingoHub API V2 (Beta)](https://developers.lingohub.com/reference/v2.md): every operation as "METHOD path: summary" (247 operations), each linking to its own page. OpenAPI spec: https://api.lingohub.com/public/api-docs/v2
- [LingoHub API V1](https://developers.lingohub.com/reference/v1.md): every operation as "METHOD path: summary" (16 operations), each linking to its own page. OpenAPI spec: https://api.lingohub.com/public/api-docs/v1
- [LingoHub CDN API](https://developers.lingohub.com/reference/cdn.md): every operation as "METHOD path: summary" (1 operation), each linking to its own page. OpenAPI spec: https://api.lingohub.com/public/api-docs/CDN

## Optional
- [All guides and recipes in one file](https://developers.lingohub.com/llms-full.txt)
- [Workflow and recovery guide as served by the API](https://api.lingohub.com/public/api-v2/guide.md): the same content as the guide above, for the deployed build
- [LingoHub Help Center](https://help.lingohub.com/): the product outside the APIs
