# Namespaces

List, create, update and delete the namespaces that group translation keys in a Comvi project.

Canonical: https://comvi.io/docs/api/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](/docs/api/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

```json
{ "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 |

```bash
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 |

```bash
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 |

```bash
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 |

```bash
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](/docs/api/translations) to create keys in a namespace
- [Import/Export](/docs/api/import-export) for bulk data by namespace
- [Namespaces in the platform](/docs/platform/namespaces) for the dashboard