Takes a snapshot of the keys and translations of a branch and gives it a name. A tag can’t be changed afterwards. Triggers the tag.created webhook.
HTTP
POST /projects/{projectId}/tagsAccess: Session token, or an API key with the keys:write scope.
Role: Project manager.
Path parameters #
| Parameter | Description |
|---|---|
projectId | The id of the project. |
Request body #
JSON.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Letters, digits, ., _, - and /, starting with a letter or digit. At most 60 characters. |
branch | string | no | The name of the branch to take the snapshot from. Defaults to main. |
JSON
{ "name": "v1.4.0", "branch": "main" }Response 201 #
The tag.
JSON
{
"id": "0197a3c8-6f75-7c66-a9bd-1d5a7e2c4f86",
"projectId": "0197a3c6-4d53-7a44-87fb-9b3e5c0a2d64",
"name": "v1.4.0",
"branch": "main",
"keys": 200,
"progress": 96,
"createdBy": "Olivia Owner",
"createdAt": "2026-10-17T09:30:00+00:00"
}Response fields #
| Field | Type | Description |
|---|---|---|
id | string | The id of the tag. |
projectId | string | The id of its project. |
name | string | The name. |
branch | string | The name of the branch the snapshot was taken from. The branch may not exist any more. |
keys | integer | How many keys the snapshot holds. |
progress | integer | Percent of key and language combinations that were published when the tag was made. |
createdBy | string or null | The name of the person who made it. null when that account was deleted. |
createdAt | string | When it was made, as an ISO 8601 time. |
Errors #
| Status | error | When |
|---|---|---|
| 401 | unauthenticated | The token is missing or not valid. |
| 403 | forbidden | You are not a manager of the project. |
| 404 | not_found | The project does not exist in your organisation, you have no access to it, or projectId is not a UUID. |
| 409 | conflict | A tag with this name exists. fields has name: taken. |
| 422 | invalid_request | name is not valid, or branch is not a branch of the project (unknown). |
| 429 | rate_limited | Too many requests, see Rate limiting. |
See Errors for the error format.