{ "openapi": "3.1.0", "info": { "title": "Localisync Translation Keys & Values", "version": "2.1.0", "description": "One project key with independent optional values per configured language. Panel session authorization; no publishing or SDK runtime lookup." }, "paths": { "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/keys": { "get": { "operationId": "listTranslationKeys", "summary": "List translation keys", "description": "All current members may read. Returns only the paged keys and up to five selected language values. Missing is based on the selected direct value, never fallback. Search matches literal text in key names and selected language values; %, _ and backslash are not wildcard patterns. Include/exclude tag filters accept comma-separated UUIDs, at most 20 each; include matches any, exclude always wins. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply. Each row includes saved direct coverage counts across all branch languages, including inactive and undisplayed ones. The languageCoverage summary counts all active branch keys independently of list filters and pagination.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "locales", "in": "query", "required": true, "description": "", "schema": { "type": "string", "description": "Comma-separated configured locale codes; one to five." } }, { "name": "q", "in": "query", "required": false, "description": "", "schema": { "type": "string", "maxLength": 200, "default": "" } }, { "name": "status", "in": "query", "required": false, "description": "", "schema": { "type": "string", "enum": [ "active", "archived", "all" ], "default": "active" } }, { "name": "filterLocale", "in": "query", "required": false, "description": "Configured language; use together with state.", "schema": { "type": "string", "minLength": 2, "maxLength": 255 } }, { "name": "state", "in": "query", "required": false, "description": "Use together with filterLocale.", "schema": { "type": "string", "enum": [ "missing", "translated", "reviewed", "unreviewed" ] } }, { "name": "includeTags", "in": "query", "description": "Comma-separated project tag UUIDs; at most 20 distinct tags.", "schema": { "type": "string" } }, { "name": "excludeTags", "in": "query", "description": "Comma-separated project tag UUIDs; at most 20 distinct tags.", "schema": { "type": "string" } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TablePage" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createTranslationKey", "summary": "Create a translation key", "description": "Owner, Admin or Editor in an active workspace/project. Creates no value rows. No language value is required. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply. Optional gitTarget assigns the key to an enabled mapping and file group in this branch in the same transaction; it never starts a provider write.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "description": "Must exactly match the configured panel origin.", "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token bound to the current opaque server session.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Retry the same payload with the same key. A changed payload requires a new key.", "schema": { "type": "string", "format": "uuid" } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKey" }, "example": { "name": "checkout_success", "format": "plain", "parameters": [] } } } }, "responses": { "201": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationKey" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/keys/{keyId}": { "get": { "operationId": "getTranslationKey", "summary": "Get a translation key", "description": "All current members may read, including archived keys. Values and history have separate paged endpoints. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationKey" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateTranslationKey", "summary": "Update a translation key", "description": "Owner, Admin or Editor. Supply the complete intended definition and expected metadata version. Every filled value must satisfy the new contract; optional active-language corrections with expected cell versions commit atomically. An incompatible language prevents all changes. Does not change project settings version. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "description": "Must exactly match the configured panel origin.", "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token bound to the current opaque server session.", "schema": { "type": "string" } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKey" }, "example": { "name": "checkout_success", "format": "icu", "parameters": [ { "name": "person", "type": "text" } ], "version": 1, "values": [] } } } }, "responses": { "200": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationKey" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/keys/{keyId}/values": { "get": { "operationId": "listTranslationValues", "summary": "List language values", "description": "All current members. Includes active and inactive configured languages and virtual Missing values with version zero. No empty database rows are created. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValuesPage" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/keys/{keyId}/values/{locale}": { "patch": { "operationId": "saveTranslationValue", "summary": "Save or clear a value", "description": "Owner, Admin or Editor. Language and all parents must be active. Both keyVersion and the cell version must match. Different language cells have independent versions. ICU requires every declared parameter with compatible usage. Limits: 16 KiB UTF-8, 10 nested expressions and 1,000 AST nodes. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "path", "required": true, "description": "", "schema": { "type": "string", "minLength": 2, "maxLength": 255 } }, { "name": "Origin", "in": "header", "required": true, "description": "Must exactly match the configured panel origin.", "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token bound to the current opaque server session.", "schema": { "type": "string" } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveValue" }, "example": { "value": "Payment successful", "version": 0, "keyVersion": 1 } } } }, "responses": { "200": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationValue" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/keys/{keyId}/archive": { "post": { "operationId": "archiveTranslationKey", "summary": "Archive a translation key", "description": "Owner/Admin only. Keeps values, history and the reserved key name. Parent workspace/project must be active. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "description": "Must exactly match the configured panel origin.", "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token bound to the current opaque server session.", "schema": { "type": "string" } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" }, "example": { "version": 1 } } } }, "responses": { "201": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationKey" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/keys/{keyId}/restore": { "post": { "operationId": "restoreTranslationKey", "summary": "Restore a translation key", "description": "Owner/Admin only. Restores the key without changing language activation or any saved value. Parent workspace/project must be active. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "description": "Must exactly match the configured panel origin.", "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token bound to the current opaque server session.", "schema": { "type": "string" } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" }, "example": { "version": 2 } } } }, "responses": { "201": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationKey" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/keys/{keyId}/history": { "get": { "operationId": "listTranslationHistory", "summary": "Read content history", "description": "All current members may read append-only content history, newest first. Includes actor, timestamp, locale, operation and before/after snapshots. There is no restore operation. Content is scoped to the explicit branch. Branch archives are read-only; current workspace roles still apply.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "description": "", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "branchId", "in": "path", "required": true, "description": "Explicit branch UUID in this project. No implicit main selection.", "schema": { "type": "string", "format": "uuid" } }, { "name": "locale", "in": "query", "required": false, "description": "Filter recorded language-specific events before pagination. Omit for complete key history, including shared definition changes. Inactive languages remain readable.", "schema": { "type": "string", "minLength": 2, "maxLength": 255 } } ], "responses": { "200": { "description": "Committed result. Responses are private and Cache-Control: no-store.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryPage" } } } }, "400": { "description": "Invalid request or ICU value; field and locale issues may be included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in to continue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current role cannot perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project or key is not visible in the current workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale version, reserved key name, archive or inactive-language conflict. Compare current data before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Mutation exceeds 1 MiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A required service is unavailable; no successful change is claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "KeyDefinition": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-sensitive letters, digits, underscore, hyphen or period. Unique in the project, including archived keys." }, "format": { "type": "string", "enum": [ "plain", "icu" ], "default": "plain" }, "parameters": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 100 }, "type": { "type": "string", "enum": [ "text", "number" ] } }, "required": [ "name", "type" ] }, "default": [] } }, "required": [ "name" ] }, "TranslationKey": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-sensitive letters, digits, underscore, hyphen or period. Unique in the project, including archived keys." }, "format": { "type": "string", "enum": [ "plain", "icu" ], "default": "plain" }, "parameters": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 100 }, "type": { "type": "string", "enum": [ "text", "number" ] } }, "required": [ "name", "type" ] }, "default": [] }, "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "additionalProperties": false } } }, "required": [ "name", "format", "parameters", "id", "workspaceId", "projectId", "version", "archivedAt", "createdAt" ] }, "TranslationValue": { "type": "object", "additionalProperties": false, "properties": { "keyId": { "type": "string", "format": "uuid" }, "locale": { "type": "string", "minLength": 2, "maxLength": 255 }, "value": { "type": [ "string", "null" ], "maxLength": 16384, "description": "At most 16 KiB UTF-8. Null, empty or whitespace-only becomes Missing; other whitespace is preserved." }, "version": { "type": "integer", "minimum": 0, "description": "Zero means no stored value yet. Clearing a stored value increments its version." }, "evidenceId": { "type": [ "string", "null" ], "format": "uuid", "description": "Current review evidence, included in matrix cells; null means Unreviewed." } }, "required": [ "keyId", "locale", "value", "version" ] }, "ValueEdit": { "type": "object", "additionalProperties": false, "properties": { "locale": { "type": "string", "minLength": 2, "maxLength": 255 }, "value": { "type": [ "string", "null" ], "maxLength": 16384, "description": "At most 16 KiB UTF-8. Null, empty or whitespace-only becomes Missing; other whitespace is preserved." }, "version": { "type": "integer", "minimum": 0, "maximum": 2147483646 } }, "required": [ "locale", "value", "version" ] }, "SaveValue": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": [ "string", "null" ], "maxLength": 16384, "description": "At most 16 KiB UTF-8. Null, empty or whitespace-only becomes Missing; other whitespace is preserved." }, "version": { "type": "integer", "minimum": 0, "maximum": 2147483646 }, "keyVersion": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "value", "version", "keyVersion" ] }, "UpdateKey": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-sensitive letters, digits, underscore, hyphen or period. Unique in the project, including archived keys." }, "format": { "type": "string", "enum": [ "plain", "icu" ] }, "parameters": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 100 }, "type": { "type": "string", "enum": [ "text", "number" ] } }, "required": [ "name", "type" ] } }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "values": { "type": "array", "maxItems": 1000, "default": [], "items": { "$ref": "#/components/schemas/ValueEdit" } } }, "required": [ "name", "format", "parameters", "version" ] }, "Version": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "version" ] }, "TablePage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-sensitive letters, digits, underscore, hyphen or period. Unique in the project, including archived keys." }, "format": { "type": "string", "enum": [ "plain", "icu" ], "default": "plain" }, "parameters": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 100 }, "type": { "type": "string", "enum": [ "text", "number" ] } }, "required": [ "name", "type" ] }, "default": [] }, "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "values": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/TranslationValue" } }, "coverage": { "type": "object", "additionalProperties": false, "description": "Direct translation coverage across all configured languages in the selected branch, including inactive and undisplayed languages. Missing and fallback values do not count. translated never exceeds total. activeTranslated counts only non-Missing direct values in active languages, including undisplayed columns; it determines whether a Missing cell has a usable assistance source. Existing translated/total coverage still includes inactive languages.", "properties": { "translated": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 1 }, "activeTranslated": { "type": "integer", "minimum": 0 } }, "required": [ "translated", "total", "activeTranslated" ] } }, "required": [ "name", "format", "parameters", "id", "workspaceId", "projectId", "version", "archivedAt", "createdAt", "values", "coverage" ] } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" }, "languageCoverage": { "type": "array", "maxItems": 5, "description": "Saved direct translation and valid review counts for every requested locale across all active keys in the explicit branch. Search, tags, key status, value/review filters and pagination do not affect these counts. Archived keys, fallback values and unsaved drafts are excluded. Inactive languages are included when requested. With no active keys, all counts are zero. Review coverage uses translated as its denominator.", "items": { "type": "object", "additionalProperties": false, "properties": { "locale": { "type": "string" }, "translated": { "type": "integer", "minimum": 0, "description": "Never exceeds total." }, "total": { "type": "integer", "minimum": 0 }, "reviewed": { "type": "integer", "minimum": 0, "description": "Nonempty saved values with unrevoked evidence matching their current text and ICU contract revisions. Never exceeds translated; translated never exceeds total." } }, "required": [ "locale", "translated", "total", "reviewed" ] } }, "canEditShared": { "type": "boolean" }, "permissions": { "type": "array", "maxItems": 5, "items": { "type": "object", "additionalProperties": false, "properties": { "locale": { "type": "string" }, "write": { "type": "boolean" }, "review": { "type": "boolean" } }, "required": [ "locale", "write", "review" ] } } }, "required": [ "items", "page", "pageSize", "hasMore", "languageCoverage", "canEditShared", "permissions" ] }, "ValuesPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "keyId": { "type": "string", "format": "uuid" }, "locale": { "type": "string", "minLength": 2, "maxLength": 255 }, "value": { "type": [ "string", "null" ], "maxLength": 16384, "description": "At most 16 KiB UTF-8. Null, empty or whitespace-only becomes Missing; other whitespace is preserved." }, "version": { "type": "integer", "minimum": 0, "description": "Zero means no stored value yet. Clearing a stored value increments its version." }, "active": { "type": "boolean" }, "writable": { "type": "boolean", "description": "Effective language write permission and active status." } }, "required": [ "keyId", "locale", "value", "version", "active", "writable" ] } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ] }, "HistoryPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "actorId": { "type": "string", "format": "uuid" }, "actorEmail": { "type": "string" }, "action": { "type": "string", "description": "Original translation/tag action or branch.merge.metadata, branch.merge.value and branch.merge.binding." }, "locale": { "type": [ "string", "null" ] }, "before": { "description": "Previous key definition, archived flag or value snapshot. Null for creation." }, "after": { "description": "Next key definition, archived flag or value snapshot." }, "createdAt": { "type": "string", "format": "date-time" }, "branchId": { "type": "string", "format": "uuid" }, "branchName": { "type": "string" }, "inherited": { "type": "boolean", "description": "Original event belongs to an ancestor or merged branch; it is not a fabricated local edit." } }, "required": [ "id", "actorId", "actorEmail", "action", "locale", "before", "after", "createdAt", "branchId", "branchName", "inherited" ] } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "object", "additionalProperties": false, "properties": { "issues": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string" }, "locale": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "issues" ] }, "statusCode": { "type": "integer", "description": "May be included by HTTP-level request limits." } }, "required": [ "error", "message" ] }, "CreateKey": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Case-sensitive letters, digits, underscore, hyphen or period. Unique in the project, including archived keys." }, "format": { "type": "string", "enum": [ "plain", "icu" ], "default": "plain" }, "parameters": { "type": "array", "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 100 }, "type": { "type": "string", "enum": [ "text", "number" ] } }, "required": [ "name", "type" ] }, "default": [] }, "gitTarget": { "type": "object", "additionalProperties": false, "required": [ "mappingId", "group", "externalName" ], "properties": { "mappingId": { "type": "string", "format": "uuid" }, "group": { "type": "string", "minLength": 1, "maxLength": 100 }, "externalName": { "type": "string", "minLength": 1, "maxLength": 200 } } } }, "required": [ "name" ] } }, "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-localisync-session", "description": "Opaque server session. Local HTTP development uses its explicitly configured development cookie name." } } } }