# Langsys Integration API (v1.0.0)

> The Langsys endpoints you can call with an API key (sent as the `X-Authorization` header), in LLM-friendly markdown. For the complete API, see https://docs.langsys.dev/llms-full.txt or https://docs.langsys.dev/api/.

## Authentication

### bearerAuth
Enter token in format (Bearer <token>)
- Type: http
- Scheme: bearer
- Name: Authorization
- In: header

### apiKey
An ApiKey security string
- Type: apiKey
- Scheme: bearer
- Name: X-Authorization
- In: header

## Auth

### GET /api/authorize-project/{projectId}
**Validate API Key for Project**

Check if api key is valid for project. Api key should be sent as a X-Authorization header.

**Parameters:**
- `projectId` (path): string (required) — Id of project

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 404: 
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.

## Utilities

### GET /api/countries/{userLocale}
**Get List of Countries in Specified Language**

Get a complete list of all countries with the country name in {localeCode} as label attribute. Pagination parameters are optional. Results can be ordered by: label, code, created_at, updated_at, id.

**Parameters:**
- `userLocale` (path): string (required) — URL paramater representing locale code to display the data in.
- `page` (query): integer — Page to request
- `records_per_page` (query): integer — Number of records per page
- `filter_by` (query): string | string[] — Filter results by field values.

Operators:
- `field:value`          equality (strict type match)
- `field:null`           field is null
- `field:!null`          field is not null
- `field:<op>:value`     comparison (op ∈ `>`, `<`, `>=`, `<=`) — numeric fields; date comparison also supported when value is `YYYY-MM-DD` (e.g. `2026-01-01`)

Multiple filters: `filter_by[]=field1:value&filter_by[]=field2:value`

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.

### GET /api/countries/dial-codes/{userLocale}
**Get List of Country Dial Codes in Specified Language**

Get a complete list of all countries dial codes with the country name in {userLocale} as name attribute. Pagination parameters are optional. Results can be ordered by: country_code, dial_code, name, created_at, updated_at, id.

**Parameters:**
- `userLocale` (path): string (required) — URL paramater representing locale code to display the data in.
- `page` (query): integer — Page to request
- `records_per_page` (query): integer — Number of records per page
- `filter_by` (query): string | string[] — Filter results by field values.

Operators:
- `field:value`          equality (strict type match)
- `field:null`           field is null
- `field:!null`          field is not null
- `field:<op>:value`     comparison (op ∈ `>`, `<`, `>=`, `<=`) — numeric fields; date comparison also supported when value is `YYYY-MM-DD` (e.g. `2026-01-01`)

Multiple filters: `filter_by[]=field1:value&filter_by[]=field2:value`

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.

### GET /api/currencies/{userLocale}
**Get List of Currencies in Specified Language**

Get a complete list of all currencies with the currency name in {localeCode} as name attribute. Pagination parameters are optional. Results can be ordered by: name, code, symbol, decimal_digits, created_at, updated_at, id.

**Parameters:**
- `userLocale` (path): string (required) — URL paramater representing locale code to display the data in.
- `page` (query): integer — Page to request
- `records_per_page` (query): integer — Number of records per page
- `order_by` (query): string | string[] — Order results by specified field(s). Supports single field (order_by=field:direction) or multiple fields for tie-breaking (order_by[]=field1:direction&order_by[]=field2:direction) <br><br>[View orderable fields and defaults](/documentation/ordering)
- `filter_by` (query): string | string[] — Filter results by field values. Supports: equality (field:value), null check (field:null), non-null check (field:!null), comparison (field:>:value, field:<:value, field:>=:value, field:<=:value). Multiple filters: filter_by[]=field1:value&filter_by[]=field2:value <br><br>[View filterable fields and defaults](/documentation/filtering)

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.

### GET /api/locales
**Get a list of locales grouped by language**

Get a list of locales grouped by language and displayed in the language of each requested locale.

**Parameters:**
- `locales[]` (query): string[] — List of locales to display the data in. Each locale in this list will be used to group data displayed in each locale's language.
- `project_id` (query): string — If provided, the project's target locales will be appended to the list of locales.
- `append_target_locales` (query): boolean — If project_id is not provided and this value is true, then the project's target locales will be appended to the list of locales. This is only when using api key authentication and project can be inferred from the api key

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `forbidden`: Forbidden.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 404: 
- 422: `validation_failed`: The request failed validation.

Possible validation errors:

- `project_id`.`invalid_format`: The project ID must be a valid UUID.
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.

### GET /api/locales/flat
**Get flat list of locales**

Get a list of all locales.

**Parameters:**
- `locales[]` (query): string[] — List of locales to display the data in. Each locale in this list will be used to group data displayed in each locale's language.
- `project_id` (query): string — If provided, the project's target locales will be appended to the list of locales.
- `append_target_locales` (query): boolean — If project_id is not provided and this value is true, then the project's target locales will be appended to the list of locales. This is only when using api key authentication and project can be inferred from the api key

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `forbidden`: Forbidden.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 404: 
- 422: `validation_failed`: The request failed validation.

Possible validation errors:

- `project_id`.`invalid_format`: The project ID must be a valid UUID.
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.

### GET /api/locales/data
**Get detailed list of locales**

Get a list of all locales with their names and language names.

**Parameters:**
- `locales[]` (query): string[] — List of locales to display the data in. Each locale in this list will be used to group data displayed in each locale's language.
- `project_id` (query): string — If provided, the project's target locales will be appended to the list of locales.
- `append_target_locales` (query): boolean — If project_id is not provided and this value is true, then the project's target locales will be appended to the list of locales. This is only when using api key authentication and project can be inferred from the api key

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `forbidden`: Forbidden.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 404: 
- 422: `validation_failed`: The request failed validation.

Possible validation errors:

- `project_id`.`invalid_format`: The project ID must be a valid UUID.
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.

## Content Discovery

### POST /api/discovery/hint
**Report a page where new content was detected**

Called by the SDK when it hits a catalog miss on a session that is not write-enabled. Reports only the page URL — never phrase content — so the page can be queued for automatic discovery. Best-effort: the response is always 204 regardless of whether a render was queued, so the endpoint reveals nothing about key validity or registration state.

**Request Body:**
Content-Type: application/json
- `page_url`: string (required) — URL of the page where the SDK hit a catalog miss on a read-only session.

**Responses:**
- 204: Hint accepted (or silently ignored)
- 422: 
- 429: 

## Translatable Items

### GET /api/translatable-items/{translatableItemId}
**Get translatable item**

Get a single phrase or a content block.

**Parameters:**
- `translatableItemId` (path): string (required) — Translatable item ID to delete
- `locale` (query): string — Locale to get the translations for. If not locale if provided, project base locale will be used.

**Responses:**
- 200: Success
- 401: 
- 403: Possible errors:

- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `forbidden`: Forbidden.
- 404: 
- 422: 
- 429: 

### POST /api/translatable-items
**Create or update translatable items**

Create a single or a list of translatable items. If a phrase that already exists is provided, the translatable attribute will be updated if it is different from the existing value. If the custom_id provided for content block already exists, the content block will be updated; this also means phrases, their translatable attributes, and their order will be updated.

**Request Body:**
Content-Type: application/json
- `project_id`: string (required)
- `translatable_items`: object[] (required)
- `custom_id`: string

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `forbidden`: Forbidden.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 404: 
- 422: Possible errors:

- `batch_size_exceeded`: The request has more translatable items than one batch allows.
- `validation_failed`: The request failed validation.

Possible validation errors:

- `translatable_items.0.phrase`.`invalid_format`: The phrase must not contain null bytes.
- `translatable_items.0.category`.`invalid_format`: The category must not contain null bytes.
- `translatable_items.0.phrases.0.phrase`.`invalid_format`: The phrase must not contain null bytes.
- `translatable_items.0.phrases.0.translations.0.translation`.`invalid_format`: The translation must not contain null bytes.
- `translatable_items.0.custom_id`.`invalid_format`: The custom ID must not contain null bytes.
- `translatable_items.0.content`.`invalid_format`: The content must not contain null bytes.
- `translatable_items.0.label`.`invalid_format`: The label must not contain null bytes.
- `translatable_items.0.translations.0.translation`.`invalid_format`: The translation must not contain null bytes.
- `translatable_items.*.phrases.*.translations.*.locale`.`invalid_option`: The locale {locale} is not a target locale of this project.
- `translatable_items.*.translations.*.locale`.`invalid_option`: The locale {locale} is not a target locale of this project.
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.

## Translations

### GET /api/translations
**List translations in flat format**

Get a list of translations. Response will be an object representing a list of translations in the form [Category] => [phrase => translation]. Content blocks will have an additional grouping by their custom_id. Translations follow the following order: [untranslated DESC, ai_translated DESC, memory_translated DESC,  translatable DESC, phrase/label ASC]

**Parameters:**
- `project_id` (query): string (required) — Project ID to get the translations for.
- `locale` (query): string (required)
- `format` (query): "flat" | "data" — Response format type. When set to 'data', the response will return the schema shown in the endpoint that has this same structure plus /data at the end. When not provided or when using flat, it returns the schema described in this endpoint.

**Responses:**
- 200: Success
- 401: 
- 402: Possible errors:

- `api_units_limit_exceeded`: Monthly API usage units limit exceeded. Upgrade your plan to continue.
- `subscription_suspended`: Subscription is suspended due to non-payment. Please pay the outstanding invoice to restore access.
- 403: Possible errors:

- `api_key_invalid`: Invalid API key
- `api_key_write_not_allowed`: This API key cannot make write requests.
- `device_mismatch`: The x-device-id header does not match the device this token was issued to.
- `forbidden`: Forbidden.
- `project_unavailable`: This project is not available. Its owners can see why in Langsys.
- 404: 
- 422: `validation_failed`: The request failed validation.

Possible validation errors:

- `locale`.`invalid_option`: The locale is not valid.
- `locale`.`invalid_option`: The locale is not a base or target locale of this project.
- 429: Possible errors:

- `duplicate_request`: Too many identical requests. Please wait a moment before retrying.
- `too_many_requests`: Too many requests. Please try again later.