Namespaces API

Namespaces let you organize translation keys into logical groups — for example, separating common, auth, and settings keys. Every project starts with a default namespace.

List namespaces

Retrieve all namespaces in a project.

GET /api/v1/projects/:projectId/namespaces

Path parameters

Parameter	Type	Required	Description
`projectId`	`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/namespaces

Example response

[
  {
    "id": 1,
    "projectId": 1,
    "namespace": "default",
    "description": null,
    "isDefault": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  },
  {
    "id": 2,
    "projectId": 1,
    "namespace": "auth",
    "description": "Authentication and login screens",
    "isDefault": false,
    "createdAt": "2025-01-16T09:00:00.000Z",
    "updatedAt": "2025-01-16T09:00:00.000Z"
  }
]

Error codes

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

Create namespace

Create a new namespace in a project.

POST /api/v1/projects/:projectId/namespaces

Path parameters

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

Request body

Field	Type	Required	Description
`namespace`	`string`	Yes	Namespace name (1-255 characters)
`description`	`string`	No	Description of what this namespace contains (max 1000 characters)
`isDefault`	`boolean`	Yes	Whether this should be the default namespace

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "auth",
    "description": "Authentication and login screens",
    "isDefault": false
  }' \
  https://api.comvi.io/api/v1/projects/1/namespaces

Example response

{
  "id": 2,
  "projectId": 1,
  "namespace": "auth",
  "description": "Authentication and login screens",
  "isDefault": false,
  "createdAt": "2025-01-16T09:00:00.000Z",
  "updatedAt": "2025-01-16T09:00:00.000Z"
}

Error codes

Status	Error	Description
`400`	`NAMESPACE_ALREADY_EXISTS`	A namespace with this name already exists in the project
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to create namespaces in this project

Update namespace

Update a namespace’s name, description, or default status.

PATCH /api/v1/projects/:projectId/namespaces/:namespaceId

Path parameters

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

Request body

Field	Type	Required	Description
`namespace`	`string`	No	Updated namespace name (1-255 characters)
`description`	`string\|null`	No	Updated description (set to `null` to clear)
`isDefault`	`boolean`	No	Set as the default namespace

Example request

curl -X PATCH \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Login, registration, and password reset screens"
  }' \
  https://api.comvi.io/api/v1/projects/1/namespaces/2

Example response

{
  "id": 2,
  "projectId": 1,
  "namespace": "auth",
  "description": "Login, registration, and password reset screens",
  "isDefault": false,
  "createdAt": "2025-01-16T09:00:00.000Z",
  "updatedAt": "2025-01-17T11:30:00.000Z"
}

Error codes

Status	Error	Description
`400`	`NAMESPACE_ALREADY_EXISTS`	A namespace with the new name already exists in the project
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to edit namespaces in this project
`404`	`NAMESPACE_NOT_FOUND`	Namespace does not exist

Delete namespace

Soft-delete a namespace. You cannot delete the default namespace or a namespace that still contains translation keys.

DELETE /api/v1/projects/:projectId/namespaces/:namespaceId

Path parameters

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

Example request

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

Example response

Returns 204 No Content with an empty body on success.

Error codes

Status	Error	Description
`400`	`CANNOT_DELETE_DEFAULT`	Cannot delete the default namespace — set another namespace as default first
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to delete namespaces in this project
`404`	`NAMESPACE_NOT_FOUND`	Namespace does not exist
`409`	`NAMESPACE_NOT_EMPTY`	Cannot delete a namespace that still contains active translation keys

Next steps

Translations API Create and manage translation keys within namespaces.

Projects API Manage projects that contain namespaces.

Import/Export API Import and export translations organized by namespace.

Namespaces (Platform) Learn about namespace management in the Comvi dashboard.