Translations API

Translation keys are the core data in Comvi. Each key belongs to a project and namespace, and holds translation values for each locale. This API lets you list, create, update, and delete keys and their values.

List translation keys

Retrieve translation keys for a project with cursor-based pagination and filtering.

GET /api/v1/projects/:projectId/keys

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Query parameters

Parameter	Type	Required	Description
`cursor`	`string`	No	Cursor from the previous response’s `nextCursor`
`limit`	`integer`	No	Items per page (1-100, default: 50)
`search`	`string`	No	Search by key name
`namespaceIds`	`integer[]`	No	Filter by namespace IDs
`statuses`	`string[]`	No	Filter by translation status: `translated`, `not_reviewed`, `not_translated`
`localeCodes`	`string[]`	No	Filter by locale codes
`sortBy`	`string`	No	Sort field: `key`, `updatedAt`, `createdAt`
`sortOrder`	`string`	No	Sort direction: `asc`, `desc`

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  "https://api.comvi.io/api/v1/projects/1/keys?limit=20&search=welcome&sortBy=key&sortOrder=asc"

Example response

{
  "data": [
    {
      "id": 42,
      "key": "welcome.message",
      "namespace": "default",
      "namespaceId": 1,
      "description": "Main welcome message on the homepage",
      "isPlural": false,
      "characterLimit": null,
      "translations": {
        "en": {
          "id": 101,
          "value": "Welcome to our app!",
          "status": "translated",
          "createdAt": "2025-01-15T10:30:00.000Z",
          "updatedAt": "2025-01-15T10:30:00.000Z",
          "createdBy": 1
        },
        "uk": {
          "id": 102,
          "value": "Ласкаво просимо!",
          "status": "translated",
          "createdAt": "2025-01-15T11:00:00.000Z",
          "updatedAt": "2025-01-15T11:00:00.000Z",
          "createdBy": 1
        }
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6NDN9",
    "hasMore": true,
    "totalItems": 250
  }
}

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to view translations in this project

Get translation key

Retrieve a single translation key with all its locale values.

GET /api/v1/projects/:projectId/keys/:keyId

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID
`keyId`	`integer`	Yes	Translation key ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/projects/1/keys/42

Example response

{
  "id": 42,
  "key": "welcome.message",
  "namespace": "default",
  "namespaceId": 1,
  "description": "Main welcome message on the homepage",
  "isPlural": false,
  "characterLimit": null,
  "translations": {
    "en": {
      "id": 101,
      "value": "Welcome to our app!",
      "status": "translated",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "createdBy": 1
    }
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to view this translation
`404`	`KEY_NOT_FOUND`	Translation key does not exist

Create translation key

Create a new translation key in a project. You can optionally include initial translation values for one or more locales.

POST /api/v1/projects/:projectId/keys

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Request body

Field	Type	Required	Description
`key`	`string`	Yes	Translation key name (1-255 characters)
`namespace`	`string`	No	Namespace name (uses `default` if omitted)
`namespaceId`	`integer`	No	Namespace ID (alternative to `namespace` name)
`description`	`string`	No	Description or context for translators (max 1000 characters)
`isPlural`	`boolean`	No	Whether this key uses ICU plural forms
`characterLimit`	`integer`	No	Maximum character count for translations
`translations`	`object`	No	Initial values keyed by locale code

`translations` object

Each entry is keyed by locale code and contains:

Field	Type	Required	Description
`value`	`string`	Yes	Translation text
`status`	`string`	Yes	Status: `translated`, `not_reviewed`, `not_translated`

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "welcome.message",
    "namespace": "default",
    "description": "Main welcome message on the homepage",
    "translations": {
      "en": {
        "value": "Welcome to our app!",
        "status": "translated"
      },
      "uk": {
        "value": "Ласкаво просимо!",
        "status": "translated"
      }
    }
  }' \
  https://api.comvi.io/api/v1/projects/1/keys

Example response

Returns 201 Created with the full translation key object (same shape as Get translation key).

Error codes

Status	Error	Description
`400`	`VALIDATION_ERROR`	Invalid request body
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to create translations
`403`	`LIMIT_EXCEEDED`	Translation key limit reached for the current plan
`409`	`KEY_ALREADY_EXISTS`	A key with this name already exists in the namespace

Update translation key

Update a translation key’s metadata. To update translation values, use the upsert translation value endpoint.

PATCH /api/v1/projects/:projectId/keys/:keyId

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID
`keyId`	`integer`	Yes	Translation key ID

Request body

Field	Type	Required	Description
`key`	`string`	No	Updated key name (1-255 characters)
`namespaceId`	`integer`	No	Move key to a different namespace
`description`	`string\|null`	No	Updated description
`isPlural`	`boolean`	No	Whether this key uses ICU plural forms
`characterLimit`	`integer\|null`	No	Updated character limit

Example request

curl -X PATCH \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated welcome message for the new homepage design",
    "characterLimit": 100
  }' \
  https://api.comvi.io/api/v1/projects/1/keys/42

Example response

Returns the full updated translation key object.

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to edit translations
`404`	`KEY_NOT_FOUND`	Translation key does not exist
`409`	`KEY_ALREADY_EXISTS`	A key with the new name already exists in the target namespace

Upsert translation value

Create or update a translation value for a specific key and locale. If a value already exists for the given locale, it is overwritten.

PUT /api/v1/projects/:projectId/keys/:key?namespace={namespace}

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID
`key`	`string`	Yes	Translation key name (URL-encoded if it contains special characters)

Query parameters

Parameter	Type	Required	Description
`namespace`	`string`	No	Namespace name (uses `default` if omitted)

Request body

Field	Type	Required	Description
`locale`	`string`	Yes	Locale code (e.g., `en`, `uk`)
`value`	`string`	Yes	Translation text
`status`	`string`	No	Status: `translated`, `not_reviewed`, `not_translated`

Example request

curl -X PUT \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "uk",
    "value": "Ласкаво просимо до нашого додатку!",
    "status": "translated"
  }' \
  "https://api.comvi.io/api/v1/projects/1/keys/welcome.message?namespace=default"

Example response

{
  "id": 102,
  "value": "Ласкаво просимо до нашого додатку!",
  "status": "translated",
  "createdAt": "2025-01-15T11:00:00.000Z",
  "updatedAt": "2025-01-16T09:15:00.000Z",
  "createdBy": 1
}

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to edit translations
`404`	`KEY_NOT_FOUND`	Translation key does not exist

Delete translation key

Soft-delete a translation key and all its values.

DELETE /api/v1/projects/:projectId/keys/:keyId

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID
`keyId`	`integer`	Yes	Translation key ID

Example request

curl -X DELETE \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/projects/1/keys/42

Example response

Returns 204 No Content with an empty body on success.

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to delete translations
`404`	`KEY_NOT_FOUND`	Translation key does not exist

Update translation status

Change the review status of a specific translation value.

PUT /api/v1/projects/:projectId/translation/:translationId/status

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID
`translationId`	`integer`	Yes	Translation value ID

Request body

Field	Type	Required	Description
`status`	`string`	Yes	New status: `translated`, `not_reviewed`, `not_translated`

Example request

curl -X PUT \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "translated"}' \
  https://api.comvi.io/api/v1/projects/1/translation/102/status

Example response

{
  "id": 102,
  "value": "Ласкаво просимо!",
  "status": "translated",
  "createdAt": "2025-01-15T11:00:00.000Z",
  "updatedAt": "2025-01-16T14:20:00.000Z",
  "createdBy": 1,
  "reviewedBy": 3,
  "reviewedAt": "2025-01-16T14:20:00.000Z"
}

Batch operations

Perform operations on multiple translation keys at once. All batch endpoints are under the /keys/batch prefix.

Batch delete

Delete multiple translation keys in a single request.

POST /api/v1/projects/:projectId/keys/batch/delete

Request body

Field	Type	Required	Description
`keyIds`	`integer[]`	Yes	Array of key IDs to delete (at least 1)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"keyIds": [42, 43, 44]}' \
  https://api.comvi.io/api/v1/projects/1/keys/batch/delete

Example response

{
  "success": true,
  "processed": 3,
  "failed": 0,
  "errors": []
}

Batch update status

Update the translation status for multiple keys at once for a specific locale.

POST /api/v1/projects/:projectId/keys/batch/status

Request body

Field	Type	Required	Description
`keyIds`	`integer[]`	Yes	Array of key IDs
`localeCode`	`string`	Yes	Locale code to update
`status`	`string`	Yes	New status: `translated`, `not_reviewed`, `not_translated`

Batch move namespace

Move multiple keys to a different namespace.

POST /api/v1/projects/:projectId/keys/batch/namespace

Request body

Field	Type	Required	Description
`keyIds`	`integer[]`	Yes	Array of key IDs
`targetNamespaceId`	`integer`	Yes	Destination namespace ID

Batch copy translations

Copy translation values from one locale to another for multiple keys.

POST /api/v1/projects/:projectId/keys/batch/copy

Request body

Field	Type	Required	Description
`keyIds`	`integer[]`	Yes	Array of key IDs
`fromLocaleCode`	`string`	Yes	Source locale code
`toLocaleCode`	`string`	Yes	Target locale code
`overwriteExisting`	`boolean`	No	Overwrite existing translations (default: false)

Batch clear translations

Clear (remove) translation values for multiple keys and locales.

POST /api/v1/projects/:projectId/keys/batch/clear

Request body

Field	Type	Required	Description
`keyIds`	`integer[]`	Yes	Array of key IDs
`localeCodes`	`string[]`	Yes	Locale codes to clear

Next steps

Import/Export API Import and export translations in bulk using JSON files.

Machine Translation API Automatically translate content using AI-powered providers.

Namespaces API Organize translation keys into logical groups.

Languages API Manage languages in your project.

Translations API

List translation keys

Path parameters

Query parameters

Example request

Example response

Error codes

Get translation key

Path parameters

Example request

Example response

Error codes

Create translation key

Path parameters

Request body

translations object

Example request

Example response

Error codes

Update translation key

Path parameters

Request body

Example request

Example response

Error codes

Upsert translation value

Path parameters

Query parameters

Request body

Example request

Example response

Error codes

Delete translation key

Path parameters

Example request

Example response

Error codes

Update translation status

Path parameters

Request body

Example request

Example response

Batch operations

Batch delete

Request body

Example request

Example response

Batch update status

Request body

Batch move namespace

Request body

Batch copy translations

Request body

Batch clear translations

Request body

Next steps

`translations` object