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

Tip

A default namespace, translation memory, and glossary are automatically created for every new project.

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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 "Authorization: Bearer comvi_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 APICreate and manage translation keys and values within your project.

Languages APIAdd and remove languages from your project.

Namespaces APIOrganize translation keys with namespaces.

AuthenticationLearn how to authenticate your API requests.