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 "Authorization: Bearer comvi_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 by namespace and name

Retrieve a single translation key with all its locale values. The project is inferred from the API key, so this route is available only with Bearer API-key authentication.

GET /api/v1/keys/:namespace/:key

Path parameters

Parameter	Type	Required	Description
namespace	string	Yes	Namespace name
key	string	Yes	Translation key name

Example request

curl -X GET \
  -H "Authorization: Bearer comvi_your_api_key" \
  https://api.comvi.io/api/v1/keys/default/welcome.message

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 "Authorization: Bearer comvi_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 by namespace and name).

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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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

Caution

Batch operations are not atomic. If some items fail, the successfully processed items are not rolled back. Check the errors array in the response for individual failures.

---

Next steps

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

Machine Translation APIAutomatically translate content using AI-powered providers.

Namespaces APIOrganize translation keys into logical groups.

Languages APIManage languages in your project.