> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nt3.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Translation Keys

> Manage translation keys within a project.

A **translation key** represents a single translatable string in your application. Each key has a unique identifier (the key name), an optional description that provides context for translators, and optional tags for organization. The actual translation values for each language are stored separately on the [Translations](/api-reference/endpoints/translations) resource.

Keys are always scoped to a project. All key endpoints require a `:projectId` path parameter.

## Endpoints

```
POST   /api/projects/:projectId/keys              Create a key
GET    /api/projects/:projectId/keys              List keys (paginated)
GET    /api/projects/:projectId/keys/:keyId       Get a key
PATCH  /api/projects/:projectId/keys/:keyId       Update a key
DELETE /api/projects/:projectId/keys/:keyId       Delete a key
POST   /api/projects/:projectId/keys/bulk         Bulk create keys
PATCH  /api/projects/:projectId/keys/bulk         Bulk update keys
DELETE /api/projects/:projectId/keys/bulk         Bulk delete keys
```

## Create a Key

```bash theme={null}
curl -X POST https://app.nt3.io/api/projects/proj_6abc123def456/keys \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "nav.home",
    "description": "Navigation bar home link label",
    "tags": ["navigation", "ui"],
    "namespace": "common"
  }'
```

**Response:**

```json theme={null}
{
  "_id": "key_abc123",
  "key": "nav.home",
  "description": "Navigation bar home link label",
  "tags": ["navigation", "ui"],
  "namespace": "common",
  "projectId": "proj_6abc123def456",
  "createdAt": "2025-03-01T10:05:00.000Z",
  "updatedAt": "2025-03-01T10:05:00.000Z"
}
```

## List Keys

Key listing is paginated. See [Pagination](/api-reference/pagination) for details.

```bash theme={null}
curl "https://app.nt3.io/api/projects/proj_6abc123def456/keys?page=1&limit=50" \
  -H "X-API-Key: entri_your_token_here"
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "_id": "key_abc123",
      "key": "nav.home",
      "description": "Navigation bar home link label"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}
```

## Get a Key

```bash theme={null}
curl https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123 \
  -H "X-API-Key: entri_your_token_here"
```

## Update a Key

All fields are optional — only included fields are changed.

```bash theme={null}
curl -X PATCH https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123 \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"description": "Revised description for translators"}'
```

## Delete a Key

Deleting a key also removes all of its translations across all languages.

```bash theme={null}
curl -X DELETE https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123 \
  -H "X-API-Key: entri_your_token_here"
```

## Bulk Operations

Use bulk endpoints when creating, updating, or deleting many keys at once. This is significantly more efficient than individual requests and reduces the risk of hitting rate limits.

**Bulk create:**

```bash theme={null}
curl -X POST https://app.nt3.io/api/projects/proj_6abc123def456/keys/bulk \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": [
      { "key": "nav.home", "description": "Home link" },
      { "key": "nav.about", "description": "About link" },
      { "key": "nav.contact", "description": "Contact link" }
    ]
  }'
```

**Bulk delete:**

```bash theme={null}
curl -X DELETE https://app.nt3.io/api/projects/proj_6abc123def456/keys/bulk \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"keyIds": ["key_abc123", "key_def456"]}'
```

## Key Notes

* Key names must be unique within a project. Attempting to create a duplicate key name returns `409 Conflict`.
* The Entri CLI uses bulk create internally when you run `entri push`.
* Tags and namespaces are optional but help organize large key sets in the editor.