Projects API

Projects are the top-level container for your translations. Each project belongs to an organization and contains translation keys, locales, and namespaces.

List projects

Retrieve all projects for an organization. Results are paginated using cursor-based pagination.

GET /api/v1/projects?organizationId={organizationId}

Query parameters

Parameter	Type	Required	Description
`organizationId`	`integer`	Yes	Organization ID to list projects for
`cursor`	`integer`	No	Cursor from previous response’s `nextCursor`
`limit`	`integer`	No	Items per page (1-100, default: 50)

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  "https://api.comvi.io/api/v1/projects?organizationId=1&limit=10"

Example response

{
  "projects": [
    {
      "id": 1,
      "organizationId": 1,
      "name": "my-web-app",
      "description": "Main web application translations",
      "sourceLocale": "en",
      "locales": [
        {
          "id": 1,
          "code": "en",
          "name": "English",
          "nativeName": "English",
          "isCustom": false,
          "flagEmoji": "🇺🇸"
        },
        {
          "id": 2,
          "code": "uk",
          "name": "Ukrainian",
          "nativeName": "Українська",
          "isCustom": false,
          "flagEmoji": "🇺🇦"
        }
      ],
      "namespaces": [
        {
          "id": 1,
          "projectId": 1,
          "namespace": "default",
          "description": null,
          "isDefault": true,
          "createdAt": "2025-01-15T10:30:00.000Z",
          "updatedAt": "2025-01-15T10:30:00.000Z"
        }
      ]
    }
  ],
  "nextCursor": 2,
  "hasMore": true
}

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No access to the specified organization

Get project

Retrieve a single project by its ID. The response includes the project’s locales, namespaces, and settings.

GET /api/v1/projects/:id

Path parameters

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

Example request

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

Example response

{
  "id": 1,
  "organizationId": 1,
  "name": "my-web-app",
  "description": "Main web application translations",
  "sourceLocale": "en",
  "locales": [
    {
      "id": 1,
      "code": "en",
      "name": "English",
      "nativeName": "English",
      "isCustom": false,
      "flagEmoji": "🇺🇸"
    }
  ],
  "namespaces": [
    {
      "id": 1,
      "projectId": 1,
      "namespace": "default",
      "description": null,
      "isDefault": true,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "mtSettings": {
    "enabledProviders": ["google", "deepl"],
    "primaryProvider": "google",
    "autoApply": false,
    "aiTranslationInstructions": null,
    "aiModels": null
  },
  "cdnSettings": {
    "enabled": true,
    "locales": ["en", "uk"],
    "namespaces": ["default"],
    "statuses": ["translated"],
    "format": "json",
    "baseUrl": null
  }
}

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to view this project
`404`	`PROJECT_NOT_FOUND`	Project does not exist

Create project

Create a new translation project in an organization. The caller must have project.create permission in the organization.

POST /api/v1/projects

Request body

Field	Type	Required	Description
`organizationId`	`integer`	Yes	Organization to create the project in
`name`	`string`	Yes	Project name (1-255 characters)
`description`	`string`	No	Project description (max 1000 characters)
`sourceLocaleCode`	`string`	Yes	Source language code (e.g., `en`, `uk`)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": 1,
    "name": "my-web-app",
    "description": "Main web application translations",
    "sourceLocaleCode": "en"
  }' \
  https://api.comvi.io/api/v1/projects

Example response

{
  "id": 1,
  "organizationId": 1,
  "name": "my-web-app",
  "description": "Main web application translations",
  "sourceLocale": "en",
  "locales": [
    {
      "id": 1,
      "code": "en",
      "name": "English",
      "nativeName": "English",
      "isCustom": false,
      "flagEmoji": "🇺🇸"
    }
  ],
  "namespaces": [
    {
      "id": 1,
      "projectId": 1,
      "namespace": "default",
      "description": null,
      "isDefault": true,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Error codes

Status	Error	Description
`400`	`LOCALE_NOT_FOUND`	The `sourceLocaleCode` is not a valid locale
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to create projects in this organization
`403`	`LIMIT_EXCEEDED`	Project limit reached for the current plan

Update project

Update a project’s name, description, source locale, machine translation settings, or CDN settings. You only need to include the fields you want to change.

PATCH /api/v1/projects/:id

Path parameters

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

Request body

Field	Type	Required	Description
`name`	`string`	No	Updated project name (1-255 characters)
`description`	`string`	No	Updated description (max 1000 characters)
`sourceLocaleCode`	`string`	No	Updated source language code
`mtSettings`	`object`	No	Machine translation configuration
`cdnSettings`	`object`	No	CDN publishing configuration

`mtSettings` object

Field	Type	Description
`enabledProviders`	`string[]`	Enabled MT providers: `google`, `deepl`, `aws`, `azure`, `openai`, `anthropic`
`primaryProvider`	`string\|null`	Default MT provider
`autoApply`	`boolean`	Automatically apply MT suggestions
`aiTranslationInstructions`	`string\|null`	Custom instructions for AI providers
`aiModels`	`object\|null`	Custom AI models per provider (e.g., `{"openai": "gpt-4o"}`)

`cdnSettings` object

Field	Type	Description
`enabled`	`boolean`	Enable CDN publishing
`locales`	`string[]`	Locale codes to include in CDN
`namespaces`	`string[]`	Namespaces to include in CDN
`statuses`	`string[]`	Translation statuses to publish: `translated`, `not_reviewed`, `not_translated`
`format`	`string`	Output format (currently `json`)

Example request

curl -X PATCH \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-web-app-v2",
    "mtSettings": {
      "enabledProviders": ["google", "deepl"],
      "primaryProvider": "google",
      "autoApply": false
    }
  }' \
  https://api.comvi.io/api/v1/projects/1

Example response

Returns the full updated project object (same shape as Get project).

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to edit this project
`404`	`PROJECT_NOT_FOUND`	Project does not exist
`404`	`LOCALE_NOT_FOUND`	The specified source locale code is invalid

Delete project

Soft-delete a project. The project and its data are retained but no longer accessible.

DELETE /api/v1/projects/:id

Path parameters

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

Example request

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

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 this project
`404`	`PROJECT_NOT_FOUND`	Project does not exist

Get project stats

Retrieve translation statistics for all projects in an organization.

GET /api/v1/projects/stats?organizationId={organizationId}

Query parameters

Parameter	Type	Required	Description
`organizationId`	`integer`	Yes	Organization ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  "https://api.comvi.io/api/v1/projects/stats?organizationId=1"

Example response

[
  {
    "projectId": 1,
    "keyCount": 250,
    "translatedPct": 85.5,
    "notReviewedPct": 10.2,
    "notTranslatedPct": 4.3
  }
]

Next steps

Translations API Create and manage translation keys and values within your project.

Languages API Add and remove languages from your project.

Namespaces API Organize translation keys with namespaces.

Authentication Learn how to authenticate your API requests.

Projects API

List projects

Query parameters

Example request

Example response

Error codes

Get project

Path parameters

Example request

Example response

Error codes

Create project

Request body

Example request

Example response

Error codes

Update project

Path parameters

Request body

mtSettings object

cdnSettings object

Example request

Example response

Error codes

Delete project

Path parameters

Example request

Example response

Error codes

Get project stats

Query parameters

Example request

Example response

Next steps

`mtSettings` object

`cdnSettings` object