Namespaces

A namespace groups translation keys, such as common, auth and settings. Every project starts with a default namespace, and keys created without a namespace go there.

All four endpoints take a session cookie or an API key: project:read to list, translations:write to create, update or delete. Common errors: 401 AUTHENTICATION_REQUIRED, 403 FORBIDDEN, 403 READ_ONLY_MODE on writes. See Errors.

Caution

Namespace endpoints do not use the standard envelope for their own failures. A duplicate name, a missing namespace or a refused delete comes back as {"error": "<sentence>"} with no code. Authentication, permission and validation failures use the standard {code, message} shape. Check for code before reading it.

Namespace object

{ "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" }

GET /v1/projects/{projectId}/namespaces

List a project’s namespaces.

Session cookie or API key with project:read.

Parameter	In	Type	Required	Meaning
projectId	path	integer	Yes	Project ID

curl -H "Authorization: Bearer $COMVI_API_KEY" https://api.comvi.io/v1/projects/1/namespaces

Returns an array of namespace objects.

POST /v1/projects/{projectId}/namespaces

Create a namespace. isDefault: true moves the default flag off the current default.

Session cookie or API key with translations:write.

Parameter	In	Type	Required	Meaning
projectId	path	integer	Yes	Project ID
namespace	body	string	Yes	1 to 255 characters
description	body	string	No	Up to 1000 characters
isDefault	body	boolean	No	Make it the default namespace

curl -X POST -H "Authorization: Bearer $COMVI_API_KEY" -H "Content-Type: application/json" \
  -d '{"namespace": "auth", "description": "Authentication and login screens"}' \
  https://api.comvi.io/v1/projects/1/namespaces

Returns 201 Created with the namespace object.

Status and body	When
400 {"error": "Namespace already exists in this project"}	A namespace with this name exists
422 FIELD_REQUIRED	namespace is missing

PATCH /v1/projects/{projectId}/namespaces/{namespaceId}

Update name, description or default status. Renaming, or moving the default flag, changes the CDN bundle layout, so a deploy is scheduled automatically.

Session cookie or API key with translations:write.

Parameter	In	Type	Required	Meaning
projectId	path	integer	Yes	Project ID
namespaceId	path	integer	Yes	Namespace ID
namespace	body	string	No	1 to 255 characters
description	body	string | null	No	null clears it
isDefault	body	boolean	No	Set as the default namespace

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

Returns the updated namespace object.

Status and body	When
400 {"error": "Namespace already exists in this project"}	The new name is taken
400 {"error": "Cannot unset the default namespace. Set another namespace as default first."}	isDefault: false on the current default
404 {"error": "Namespace not found"}	No such namespace in the project

DELETE /v1/projects/{projectId}/namespaces/{namespaceId}

Soft-delete a namespace. The default namespace, and one that still holds keys, cannot be deleted: move or delete the keys first, and set another default first.

Session cookie or API key with translations:write.

Parameter	In	Type	Required	Meaning
projectId	path	integer	Yes	Project ID
namespaceId	path	integer	Yes	Namespace ID

curl -X DELETE -H "Authorization: Bearer $COMVI_API_KEY" https://api.comvi.io/v1/projects/1/namespaces/2

Returns 204 No Content.

Status and body	When
400 {"error": "Cannot delete the default namespace. Set another namespace as default first."}	The namespace is the default
404 {"error": "Namespace not found"}	No such namespace in the project
409 {"error": "Cannot delete namespace with active translation keys"}	The namespace still holds active keys

Next steps

• Translations to create keys in a namespace
• Import/Export for bulk data by namespace
• Namespaces in the platform for the dashboard