---
title: "Create translation key"
method: POST
path: "/api/v1/translation-keys"
tags: ["Translation keys"]
---

# Create translation key

`POST /api/v1/translation-keys`

## Request

- Base URL: `https://api.simplelocalize.io`
- URL: `https://api.simplelocalize.io/api/v1/translation-keys`
- Auth: API key in header `X-SimpleLocalize-Token`
- TypeScript: <https://skmtc.dev/simplelocalize/apis/simplelocalize-api/docs/api/v1/translation-keys/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates translation key for a project. It throws an error if translation key already exists.

`key` is a required field, and it cannot be null or empty. The endpoint throws an error if `key` is null or empty.

`namespace`, `description` and `codeDescription` are optional fields, and they can be null or empty. Null and empty values are ignored.

Max size of `description` and `codeDescription` is 500 characters, otherwise, the endpoint throws an error.

If `namespace` is not provided, the default namespace is used.

If `description` is not provided, the empty string is used. Description is used for translation key comments that are visible in the editor, and they be edited in the editor.

If `codeDescription` is not provided, the empty string is used. Code description is used for code comments that are visible in the editor, but they cannot be edited in the editor.

If `charactersLimit` is not provided (or -1), then no limit is set.

Set `lock: true` to prevent the translation key from being modified.

Set `deprecated: true` to mark the translation key as deprecated in the Web UI.

## Request body

- CreateTranslationKeyRequestV2
  - `key` string, required
  - `namespace` string
  - `description` string
  - `codeDescription` string
  - `charactersLimit` integer
  - `lock` boolean
  - `deprecated` boolean
  - `tags` string[]
  - `attributes` object

## Response `200`

OK

## Other responses

- `400`: Bad Request
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-11-07** `67a25a25863a`: 3 info
  - added the new optional request property `attributes`
  - added the new optional request property `deprecated`
  - added the new optional request property `lock`
- **2025-11-12** `0329534cd557`: 1 warning, 16 info
  - deleted the `header` request parameter `X-SimpleLocalize-Token`
  - the endpoint scheme security `Project API Key` was added to the API
  - the endpoint scheme security `apiKey` was removed from the API
  - added the optional property `title` to the response with the `400` status
  - …13 more
- **2025-04-19** `5475c7163be9`: 10 info
  - added the new optional request property `charactersLimit`
  - added the new optional request property `tags`
  - the `namespace` request property's maxLength was increased from `64` to `128`
  - added the optional property `code` to the response with the `400` status
  - …6 more
- **2023-11-30** `18bfbf87af44`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/simplelocalize/apis/simplelocalize-api/changes/api/v1/translation-keys/post.md)

---

[API](https://skmtc.dev/simplelocalize/apis/simplelocalize-api.md) - [All operations](https://skmtc.dev/simplelocalize/apis/simplelocalize-api/llms.txt) - [OpenAPI document](https://skmtc.dev/simplelocalize/apis/simplelocalize-api/revisions/67a25a25863a?raw)