Tolgee Octri Demo
POST/v2/projects/{projectId}/keys

Create a localization key

Creates a localization key in a project and can include translations, tags, screenshots, and translation states. Supply name and isPlural; use translations and relatedKeysInOrder to provide translation values and contextual keys. The response contains the created key and its generated identifier.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 13 body fields
projectIdintegerrequired
The numeric identifier of the project in which to create the key.

The localization key details, with name and isPlural required.

branchstringoptional
The branch in which to create the key.
descriptionstringoptional
Description of the key
isPluralbooleanrequired
If key is pluralized. If it will be reflected in the editor
maxCharLimitintegeroptional
Maximum character limit for translations of this key. Null means no limit.
namestringrequired
Name of the key
namespacestringoptional
The namespace of the key. (When empty or null default namespace will be used)
pluralArgNamestringoptional
The argument name for the plural. If null, value will be guessed from the values provided in translations.
relatedKeysInOrderarray<object>optional
Keys in the document used as a context for machine translation. Keys in the same order as they appear in the document. The order is important! We are using it for graph distance calculation.
screenshotUploadedImageIdsarray<integer>deprecatedoptional
Ids of screenshots uploaded with /v2/image-upload endpoint
screenshotsarray<object>optional
Screenshots to associate with the key. Each screenshot must include an `uploadedImageId` and can include text and positions.
statesobjectoptional
Translation states to update, if not provided states won't be modified
tagsarray<string>optional
Tags to associate with the key.
translationsobjectoptional
Translation values keyed by language.

5 status codes
201Returns the created key, including its ID, name, pluralization setting, screenshots, tags, and translations.
branchstringoptional
Branch of the key
customobjectrequired
Custom values of the key
descriptionstringoptional
Description of key
idintegerrequired
Id of key record
isPluralbooleanrequired
If key is pluralized. If it will be reflected in the editor
maxCharLimitintegeroptional
Maximum character limit for translations of this key
namestringrequired
Name of key
namespacestringoptional
Namespace of key
pluralArgNamestringoptional
The argument name for the plural
screenshotsarray<object>required
Screenshots of the key
tagsarray<object>required
Tags of key
translationsobjectrequired
Translations object containing values updated in this request
400Returned when the request is invalid, such as when a required field is missing or a value fails validation.
codestringrequired
Allowed:unauthenticatedapi_access_forbiddenapi_key_not_foundinvalid_api_keyinvalid_project_api_keyproject_api_key_expiredbad_credentialsmfa_enabledinvalid_otp_codemfa_not_enabledcan_not_revoke_own_permissionsdata_corrupted
paramsarray<object>optional
401Returned when the request is unauthenticated.
codestringrequired
Allowed:unauthenticatedapi_access_forbiddenapi_key_not_foundinvalid_api_keyinvalid_project_api_keyproject_api_key_expiredbad_credentialsmfa_enabledinvalid_otp_codemfa_not_enabledcan_not_revoke_own_permissionsdata_corrupted
paramsarray<object>optional
403Returned when access to the requested resource is forbidden.
codestringrequired
Allowed:unauthenticatedapi_access_forbiddenapi_key_not_foundinvalid_api_keyinvalid_project_api_keyproject_api_key_expiredbad_credentialsmfa_enabledinvalid_otp_codemfa_not_enabledcan_not_revoke_own_permissionsdata_corrupted
paramsarray<object>optional
404Returned when the project or requested resource is not found.
codestringrequired
Allowed:unauthenticatedapi_access_forbiddenapi_key_not_foundinvalid_api_keyinvalid_project_api_keyproject_api_key_expiredbad_credentialsmfa_enabledinvalid_otp_codemfa_not_enabledcan_not_revoke_own_permissionsdata_corrupted
paramsarray<object>optional

Error handling

A 400 is returned for a malformed request, a 401 when the request is unauthenticated, a 403 when access is forbidden, and a 404 when the project or requested resource is not found. The projectId path parameter must identify the project. name and isPlural are required, name must contain at least one character, and relatedKeysInOrder entries must include a non-empty keyName; states values must be TRANSLATED or REVIEWED.