{ "openapi": "3.1.0", "info": { "title": "General Translation API", "version": "2026-03-06.v1", "description": "Translate content and manage projects with the General Translation API at `https://api.gtx.dev`.\n\nAuthenticate with `Authorization: Bearer `. Each endpoint lists its required permissions. Project keys (`gtx-api-`) access one project; Organization keys (`gtx-org-`) access projects in one Organization.\n\nFor project-scoped requests, use the project ID in the path. If you also send `gt-project-id`, it must match. Without a project ID in the path, project keys use their own project; Organization keys require `gt-project-id`. Discovery endpoints need no project ID. Organization-scoped requests use the Organization ID in the path. You must have access to the selected project or Organization.", "contact": { "name": "General Translation Support", "email": "support@generaltranslation.com", "url": "https://generaltranslation.com" } }, "servers": [ { "url": "https://api.gtx.dev", "description": "General Translation API" } ], "tags": [ { "name": "Files", "description": "Upload, download, publish, move, and inspect project files." }, { "name": "Context", "description": "Generate translation context such as glossaries and instructions." }, { "name": "Context Management", "description": "Manage context groups, glossary terms, custom prompts, and project assignments." }, { "name": "Translation", "description": "Translate content, queue files for translation, and read translation job status." }, { "name": "Project", "description": "Create and manage projects, assets, branches, and file version tags." }, { "name": "Integrations", "description": "Internal Figma and Google Drive plugin operations." }, { "name": "CLI Wizard", "description": "Create and manage internal CLI wizard sessions." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Project or organization API key." }, "UserBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.1 user access token.", "x-internal": true }, "GoogleIdentityToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Google identity token for the Workspace plugin." } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] }, "ApiVersion": { "type": "string", "enum": [ "2025-01-01.v0", "2025-11-03.v1", "2026-02-18.v1", "2026-03-06.v1" ], "description": "API contract version. Defaults to the oldest supported version." }, "FileFormat": { "type": "string", "enum": [ "GTJSON", "MDX", "JSON", "YAML", "MD", "TS", "JS", "HTML", "TXT", "PO", "POT", "TWILIO_CONTENT_JSON", "LOTTIE", "SVG", "XCSTRINGS", "DOT_STRINGS", "DOT_STRINGSDICT", "ANDROID_STRINGS", "SRT", "RESX" ] }, "JsonObject": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "JsonValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/JsonValue" }, { "type": "null" } ] } }, { "type": "object", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/JsonValue" }, { "type": "null" } ] } } ] }, "DataFormat": { "type": "string", "enum": ["JSX", "ICU", "I18NEXT", "STRING"] }, "ModelProvider": { "type": "string", "enum": ["ANTHROPIC", "OPENAI", "XAI", "GOOGLE", "HYPERCLOVA"] }, "Branch": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "RuntimeTranslationResponse": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true] }, "translation": { "$ref": "#/components/schemas/JsonValue" }, "dataFormat": { "$ref": "#/components/schemas/DataFormat" }, "locale": { "type": "string" } }, "required": ["success", "dataFormat", "locale"] }, { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false] }, "error": { "type": "string" }, "code": { "type": "number" } }, "required": ["success", "error", "code"] } ] } }, "RuntimeTranslationRequest": { "type": "object", "properties": { "requests": { "type": "object", "additionalProperties": { "type": "object", "properties": { "source": {}, "metadata": { "type": "object", "properties": { "id": { "type": "string" }, "hash": { "type": "string" }, "context": { "type": "string" }, "maxChars": { "type": "number" }, "dataFormat": { "$ref": "#/components/schemas/DataFormat" }, "fileFormat": { "$ref": "#/components/schemas/RuntimeFileFormat" }, "actionType": { "type": "string", "enum": ["fast", "standard"], "default": "fast" }, "sourceCode": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "before": { "type": "string" }, "target": { "type": "string" }, "after": { "type": "string" } }, "required": ["before", "target", "after"] } } } }, "default": { "dataFormat": "STRING", "actionType": "fast" } } } } }, "targetLocale": { "type": "string", "minLength": 1 }, "sourceLocale": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "properties": { "modelProvider": { "$ref": "#/components/schemas/ModelProvider" } } } }, "required": ["requests", "targetLocale", "sourceLocale", "metadata"] }, "RuntimeFileFormat": { "type": "string", "enum": ["MD", "MDX"] }, "ProjectApiKeyPermission": { "type": "string", "enum": [ "project:write", "project:context:read", "project:context:write", "project:files:read", "project:files:write", "project:translations:generate", "project:translations:enqueue" ] }, "ContextGroup": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "CreateCliWizardSessionResponse": { "type": "object", "properties": { "sessionId": { "type": "string" } }, "required": ["sessionId"] }, "CreateCliWizardSessionRequest": { "type": "object", "properties": { "keyType": { "$ref": "#/components/schemas/CliKeyType" } } }, "CliKeyType": { "type": "string", "enum": ["development", "production", "all"], "default": "production", "deprecated": true, "description": "Deprecated: the wizard creates one project API key and returns it in each requested slot." }, "CliWizardSessionReadyResponse": { "anyOf": [ { "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "$ref": "#/components/schemas/ApiKeyType" } }, "required": ["key", "type"] } }, "projectId": { "type": "string" } }, "required": ["apiKeys", "projectId"] }, { "type": "object", "properties": { "apiKey": { "type": "string" }, "projectId": { "type": "string" } }, "required": ["apiKey", "projectId"] } ] }, "ApiKeyType": { "type": "string", "enum": ["development", "production"] }, "CliWizardSessionWaitingResponse": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] }, "DeleteCliWizardSessionResponse": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] } }, "parameters": {} }, "paths": { "/v1/integrations/workspace-plugin/translate": { "post": { "operationId": "workspacePluginTranslate", "x-internal": true, "summary": "Workspace plugin translate", "description": "Run the Google Drive Workspace plugin translate command.", "tags": ["Integrations"], "security": [ { "GoogleIdentityToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "GT project ID returned by get_google_drive_context. The project must have a Google Drive integration connected in the GT dashboard." }, "fileId": { "type": "string", "minLength": 1, "description": "File ID assigned by Google Drive, found in the Google Docs or Slides URL after /d/. This is not a GT database file ID. May identify a source file or a GT-managed translated copy." }, "hostApp": { "type": "string", "enum": ["DOCS", "SLIDES"], "description": "Google editor for the file: DOCS for Google Docs or SLIDES for Google Slides." }, "targetLocales": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100, "description": "One to 100 supported target locale codes, such as fr or es-MX. Must respect the project locale whitelist. For a GT-managed translated copy, only that copy’s target locale is used." }, "sourceLocale": { "type": "string", "minLength": 1, "description": "Optional source locale code, such as en. Defaults to the file’s stored source locale, then the project default. Ignored for a GT-managed translated copy, whose original source locale is used." }, "force": { "type": "boolean", "description": "Whether to force retranslation of existing translations. Defaults to false. Retranslation may incur additional translation charges." } }, "required": ["projectId", "fileId", "hostApp", "targetLocales"] } } } }, "responses": { "200": { "description": "Workspace plugin result", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "sourceLocale": { "type": "string" }, "targetLocales": { "type": "array", "items": { "type": "string" } }, "enqueued": { "type": "number" }, "failed": { "type": "number" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "accepted", "sourceLocale", "targetLocales", "enqueued", "failed", "errors" ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "502": { "description": "Translation could not be started for any of the requested locales.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/workspace-plugin/status": { "post": { "operationId": "workspacePluginStatus", "x-internal": true, "summary": "Workspace plugin status", "description": "Run the Google Drive Workspace plugin status command.", "tags": ["Integrations"], "security": [ { "GoogleIdentityToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "GT project ID returned by get_google_drive_context. The project must have a Google Drive integration connected in the GT dashboard." }, "fileId": { "type": "string", "minLength": 1, "description": "File ID assigned by Google Drive, found in the Google Docs or Slides URL after /d/. This is not a GT database file ID. May identify a source file or a GT-managed translated copy." }, "hostApp": { "type": "string", "enum": ["DOCS", "SLIDES"], "description": "Google editor for the file: DOCS for Google Docs or SLIDES for Google Slides." } }, "required": ["projectId", "fileId", "hostApp"] } } } }, "responses": { "200": { "description": "Workspace plugin result", "content": { "application/json": { "schema": { "type": "object", "properties": { "locales": { "type": "array", "items": { "type": "object", "properties": { "targetLocale": { "type": "string" }, "locale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "translationProgress": { "type": ["number", "null"] }, "layoutProgress": { "type": ["number", "null"] }, "done": { "type": "boolean" }, "targetCopy": { "type": "object", "properties": { "fileId": { "type": "string" }, "url": { "type": "string" } }, "required": ["fileId", "url"] } }, "required": [ "targetLocale", "locale", "translationProgress", "layoutProgress", "done" ] } } }, "required": ["locales"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "502": { "description": "An upstream service failed to complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/plugins/{provider}/info": { "post": { "operationId": "pluginInfo", "x-internal": true, "summary": "Plugin info", "description": "Run the info command for a design-tool plugin.", "tags": ["Integrations"], "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": ["figma", "after-effects"] }, "required": true, "name": "provider", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["fileName"], "additionalProperties": false }, { "type": "object", "properties": { "projectStamp": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["projectStamp"], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Plugin command result", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "integrationId": { "type": "string" }, "sourceLocale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "currentLocales": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "localeWhitelist": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } } }, "required": [ "id", "name", "integrationId", "sourceLocale", "currentLocales", "localeWhitelist" ] }, "supportedLocales": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "linked": { "type": "array", "items": { "type": "object", "properties": { "pageId": { "type": "string" }, "pageName": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "sourceLocale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "locales": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "updatedAt": { "type": "string" }, "skippedCount": { "type": "number" }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "structuralPath": { "type": "string", "minLength": 1, "maxLength": 1024 }, "displayPath": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "reason": { "type": "string", "enum": [ "not_text_node", "empty_text", "hidden_layer", "missing_characters" ] }, "details": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "key", "structuralPath", "displayPath", "reason" ], "additionalProperties": false } } }, "required": [ "pageId", "pageName", "fileId", "versionId", "sourceLocale", "locales", "updatedAt", "skippedCount", "skipped" ] } } }, "required": ["project", "supportedLocales", "linked"] }, { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "integrationId": { "type": "string" }, "sourceLocale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "currentLocales": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "localeWhitelist": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } } }, "required": [ "id", "name", "integrationId", "sourceLocale", "currentLocales", "localeWhitelist" ] }, "supportedLocales": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "linked": { "type": "array", "items": { "type": "object", "properties": { "compId": { "type": "string" }, "compName": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "sourceLocale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "locales": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "updatedAt": { "type": "string" }, "skippedCount": { "type": "number" }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "structuralPath": { "type": "string", "minLength": 1, "maxLength": 1024 }, "displayPath": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "reason": { "type": "string", "enum": [ "not_text_layer", "empty_text", "expression_driven", "essential_graphics" ] }, "details": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "key", "structuralPath", "displayPath", "reason" ], "additionalProperties": false } } }, "required": [ "compId", "compName", "fileId", "versionId", "sourceLocale", "locales", "updatedAt", "skippedCount", "skipped" ] } } }, "required": ["project", "supportedLocales", "linked"] } ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "423": { "description": "The resource is locked by an operation in progress. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/plugins/{provider}/layout": { "post": { "operationId": "pluginLayout", "x-internal": true, "summary": "Plugin layout", "description": "Run the layout command for a design-tool plugin.", "tags": ["Integrations"], "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": ["figma", "after-effects"] }, "required": true, "name": "provider", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "pageId": { "type": "string", "minLength": 1, "maxLength": 255 }, "locale": { "type": "string", "minLength": 2, "maxLength": 16 }, "frames": { "type": "array", "items": { "type": "object", "properties": { "frameId": { "type": "string", "minLength": 1, "maxLength": 255 }, "frameName": { "type": "string", "maxLength": 255 }, "before": { "type": "object", "properties": { "mediaType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "base64": { "type": "string", "minLength": 1, "maxLength": 6000000 } }, "required": ["mediaType", "base64"], "additionalProperties": false }, "after": { "type": "object", "properties": { "mediaType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "base64": { "type": "string", "minLength": 1, "maxLength": 6000000 } }, "required": ["mediaType", "base64"], "additionalProperties": false }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "rect": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": ["x", "y", "width", "height"], "additionalProperties": false }, "text": { "type": "string", "maxLength": 4000 }, "measuredOverflow": { "type": "boolean" }, "measuredCollision": { "type": "boolean" } }, "required": ["nodeId", "rect", "text"], "additionalProperties": false }, "maxItems": 200 } }, "required": ["frameId", "before", "after", "nodes"], "additionalProperties": false }, "minItems": 1, "maxItems": 4 } }, "required": ["fileName", "pageId", "locale", "frames"], "additionalProperties": false }, { "type": "object", "properties": {}, "additionalProperties": {} } ] } } } }, "responses": { "200": { "description": "Plugin command result", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "frames": { "type": "array", "items": { "type": "object", "properties": { "frameId": { "type": "string" }, "remedies": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string" }, "rephrase": { "type": "string" } }, "required": ["nodeId", "rephrase"] } } }, "required": ["frameId", "remedies"] } } }, "required": ["frames"] }, { "type": "object", "properties": {}, "additionalProperties": false } ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "423": { "description": "The resource is locked by an operation in progress. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/plugins/{provider}/sync": { "post": { "operationId": "pluginSync", "x-internal": true, "summary": "Plugin sync", "description": "Run the sync command for a design-tool plugin.", "tags": ["Integrations"], "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": ["figma", "after-effects"] }, "required": true, "name": "provider", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "pageId": { "type": "string", "minLength": 1, "maxLength": 255 }, "pageName": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceLocale": { "type": "string", "minLength": 2, "maxLength": 16 }, "units": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "structuralPath": { "type": "string", "minLength": 1, "maxLength": 1024 }, "value": { "type": "string" }, "displayPath": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "layout": { "type": "object", "properties": { "boxId": { "type": "string", "minLength": 1, "maxLength": 255 }, "frameId": { "type": "string", "minLength": 1, "maxLength": 255 }, "rect": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": ["x", "y", "width", "height"], "additionalProperties": false }, "render": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": ["x", "y", "width", "height"], "additionalProperties": false }, "room": { "type": "object", "properties": { "left": { "type": "number", "minimum": 0 }, "right": { "type": "number", "minimum": 0 }, "up": { "type": "number", "minimum": 0 }, "down": { "type": "number", "minimum": 0 } }, "required": ["left", "right", "up", "down"], "additionalProperties": false }, "autoResize": { "type": "string", "enum": [ "NONE", "HEIGHT", "WIDTH_AND_HEIGHT", "TRUNCATE" ] }, "textAlignHorizontal": { "type": "string", "enum": [ "LEFT", "CENTER", "RIGHT", "JUSTIFIED" ] }, "baseFontPt": { "type": "number" }, "equivClass": { "type": "string", "maxLength": 255 }, "sizeRank": { "type": "number" } }, "required": ["boxId"], "additionalProperties": false }, "styleRuns": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 }, "style": { "type": "object", "properties": { "fontName": { "type": "object", "properties": { "family": { "type": "string" }, "style": { "type": "string" } }, "required": ["family", "style"], "additionalProperties": false }, "fontSize": { "type": "number" }, "textDecoration": { "type": "string" }, "textCase": { "type": "string" }, "letterSpacing": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": ["value", "unit"], "additionalProperties": false }, "lineHeight": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": ["unit"], "additionalProperties": false }, "fills": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "hyperlink": { "type": ["object", "null"], "additionalProperties": {} } }, "additionalProperties": false } }, "required": ["start", "end", "style"], "additionalProperties": false }, "maxItems": 512 }, "instanceTextOrigin": { "type": "string", "enum": ["inherited", "overridden"] } }, "required": [ "key", "structuralPath", "value", "displayPath" ], "additionalProperties": false }, "maxItems": 20000 }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "structuralPath": { "type": "string", "minLength": 1, "maxLength": 1024 }, "displayPath": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "reason": { "type": "string", "enum": [ "not_text_node", "empty_text", "hidden_layer", "missing_characters" ] }, "details": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "key", "structuralPath", "displayPath", "reason" ], "additionalProperties": false }, "maxItems": 20000 }, "allIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 500 } }, "required": ["fileName", "pageId", "pageName", "units"], "additionalProperties": false }, { "type": "object", "properties": { "projectStamp": { "type": "string", "minLength": 1, "maxLength": 255 }, "compId": { "type": "string", "minLength": 1, "maxLength": 255 }, "compName": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceLocale": { "type": "string", "minLength": 2, "maxLength": 16 }, "units": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "structuralPath": { "type": "string", "minLength": 1, "maxLength": 1024 }, "value": { "type": "string" }, "displayPath": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "styleRuns": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 }, "style": { "type": "object", "properties": { "font": { "type": "string", "maxLength": 255 }, "fontSize": { "type": "number" }, "fillColor": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "applyFill": { "type": "boolean" }, "fauxBold": { "type": "boolean" }, "fauxItalic": { "type": "boolean" }, "tracking": { "type": "number" }, "applyStroke": { "type": "boolean" }, "strokeColor": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "strokeWidth": { "type": "number" } }, "additionalProperties": false } }, "required": ["start", "end", "style"], "additionalProperties": false }, "maxItems": 512 }, "layout": { "type": "object", "properties": { "boxText": { "type": "boolean" }, "boxSize": { "type": "array", "prefixItems": [ { "type": "number", "minimum": 0 }, { "type": "number", "minimum": 0 } ] }, "fontSize": { "type": "number", "minimum": 0 } }, "required": ["boxText"], "additionalProperties": false } }, "required": [ "key", "structuralPath", "value", "displayPath" ], "additionalProperties": false }, "maxItems": 20000 }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "structuralPath": { "type": "string", "minLength": 1, "maxLength": 1024 }, "displayPath": { "type": "array", "items": { "type": "string" }, "maxItems": 64 }, "reason": { "type": "string", "enum": [ "not_text_layer", "empty_text", "expression_driven", "essential_graphics" ] }, "details": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "key", "structuralPath", "displayPath", "reason" ], "additionalProperties": false }, "maxItems": 20000 }, "allIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 500 } }, "required": ["projectStamp", "compId", "compName", "units"], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Plugin command result", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "fileId": { "type": "string" }, "versionId": { "type": "string" }, "sourceLocale": { "type": "string" }, "unitCount": { "type": "number" }, "skippedCount": { "type": "number" }, "movedFrom": { "type": "string" } }, "required": [ "fileId", "versionId", "sourceLocale", "unitCount", "skippedCount" ] }, { "type": "object", "properties": { "fileId": { "type": "string" }, "versionId": { "type": "string" }, "sourceLocale": { "type": "string" }, "unitCount": { "type": "number" }, "skippedCount": { "type": "number" }, "movedFrom": { "type": "string" } }, "required": [ "fileId", "versionId", "sourceLocale", "unitCount", "skippedCount" ] } ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "423": { "description": "The resource is locked by an operation in progress. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/plugins/{provider}/import-translations": { "post": { "operationId": "pluginImportTranslations", "x-internal": true, "summary": "Plugin import-translations", "description": "Run the import-translations command for a design-tool plugin.", "tags": ["Integrations"], "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": ["figma", "after-effects"] }, "required": true, "name": "provider", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "pageId": { "type": "string", "minLength": 1, "maxLength": 255 }, "locale": { "type": "string", "minLength": 2, "maxLength": 16 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "translations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string" }, "styleRuns": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 }, "style": { "type": "object", "properties": { "fontName": { "type": "object", "properties": { "family": { "type": "string" }, "style": { "type": "string" } }, "required": ["family", "style"], "additionalProperties": false }, "fontSize": { "type": "number" }, "textDecoration": { "type": "string" }, "textCase": { "type": "string" }, "letterSpacing": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": ["value", "unit"], "additionalProperties": false }, "lineHeight": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": ["unit"], "additionalProperties": false }, "fills": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "hyperlink": { "type": ["object", "null"], "additionalProperties": {} } }, "additionalProperties": false } }, "required": ["start", "end", "style"], "additionalProperties": false }, "maxItems": 512 } }, "required": ["text"], "additionalProperties": false } } }, "required": [ "fileName", "pageId", "locale", "versionId", "translations" ], "additionalProperties": false }, { "type": "object", "properties": { "projectStamp": { "type": "string", "minLength": 1, "maxLength": 255 }, "compId": { "type": "string", "minLength": 1, "maxLength": 255 }, "locale": { "type": "string", "minLength": 2, "maxLength": 16 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "translations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string" }, "styleRuns": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 }, "style": { "type": "object", "properties": { "font": { "type": "string", "maxLength": 255 }, "fontSize": { "type": "number" }, "fillColor": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "applyFill": { "type": "boolean" }, "fauxBold": { "type": "boolean" }, "fauxItalic": { "type": "boolean" }, "tracking": { "type": "number" }, "applyStroke": { "type": "boolean" }, "strokeColor": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "strokeWidth": { "type": "number" } }, "additionalProperties": false } }, "required": ["start", "end", "style"], "additionalProperties": false }, "maxItems": 512 } }, "required": ["text"], "additionalProperties": false } } }, "required": [ "projectStamp", "compId", "locale", "versionId", "translations" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Plugin command result", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "saved": { "type": "boolean" }, "versionId": { "type": "string" }, "importedCount": { "type": "number" }, "unmatchedCount": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reason": { "type": "string" }, "detail": { "type": "string" } }, "required": ["key", "reason"] } } }, "required": [ "saved", "versionId", "importedCount", "unmatchedCount", "warnings" ] }, { "type": "object", "properties": { "saved": { "type": "boolean" }, "versionId": { "type": "string" }, "importedCount": { "type": "number" }, "unmatchedCount": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reason": { "type": "string" }, "detail": { "type": "string" } }, "required": ["key", "reason"] } } }, "required": [ "saved", "versionId", "importedCount", "unmatchedCount", "warnings" ] } ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "423": { "description": "A translation is still running for the requested locale. Retry once it finishes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/plugins/{provider}/enqueue": { "post": { "operationId": "pluginEnqueue", "x-internal": true, "summary": "Plugin enqueue", "description": "Run the enqueue command for a design-tool plugin.", "tags": ["Integrations"], "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": ["figma", "after-effects"] }, "required": true, "name": "provider", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "pageId": { "type": "string", "minLength": 1, "maxLength": 255 }, "targetLocales": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 16 }, "minItems": 1, "maxItems": 64 }, "sourceLocale": { "type": "string", "minLength": 2, "maxLength": 16 }, "force": { "type": "boolean" } }, "required": ["fileName", "pageId", "targetLocales"], "additionalProperties": false }, { "type": "object", "properties": { "projectStamp": { "type": "string", "minLength": 1, "maxLength": 255 }, "compId": { "type": "string", "minLength": 1, "maxLength": 255 }, "targetLocales": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 16 }, "minItems": 1, "maxItems": 64 }, "sourceLocale": { "type": "string", "minLength": 2, "maxLength": 16 }, "force": { "type": "boolean" } }, "required": ["projectStamp", "compId", "targetLocales"], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Plugin command result", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "accepted": { "type": "boolean" }, "sourceLocale": { "type": "string" }, "targetLocales": { "type": "array", "items": { "type": "string" } }, "versionId": { "type": "string" } }, "required": [ "accepted", "sourceLocale", "targetLocales", "versionId" ] }, { "type": "object", "properties": { "accepted": { "type": "boolean" }, "sourceLocale": { "type": "string" }, "targetLocales": { "type": "array", "items": { "type": "string" } }, "versionId": { "type": "string" } }, "required": [ "accepted", "sourceLocale", "targetLocales", "versionId" ] } ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "423": { "description": "The resource is locked by an operation in progress. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/plugins/{provider}/status": { "post": { "operationId": "pluginStatus", "x-internal": true, "summary": "Plugin status", "description": "Run the status command for a design-tool plugin.", "tags": ["Integrations"], "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": ["figma", "after-effects"] }, "required": true, "name": "provider", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "pageId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["fileName", "pageId"], "additionalProperties": false }, { "type": "object", "properties": { "projectStamp": { "type": "string", "minLength": 1, "maxLength": 255 }, "compId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": ["projectStamp", "compId"], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Plugin command result", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "versionId": { "type": "string" }, "locales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "translationProgress": { "type": ["number", "null"] }, "done": { "type": "boolean" } }, "required": [ "locale", "translationProgress", "done" ] } } }, "required": ["versionId", "locales"] }, { "type": "object", "properties": { "versionId": { "type": "string" }, "locales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "translationProgress": { "type": ["number", "null"] }, "done": { "type": "boolean" } }, "required": [ "locale", "translationProgress", "done" ] } } }, "required": ["versionId", "locales"] } ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "423": { "description": "The resource is locked by an operation in progress. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/plugins/{provider}/download": { "post": { "operationId": "pluginDownload", "x-internal": true, "summary": "Plugin download", "description": "Run the download command for a design-tool plugin.", "tags": ["Integrations"], "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": ["figma", "after-effects"] }, "required": true, "name": "provider", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "pageId": { "type": "string", "minLength": 1, "maxLength": 255 }, "locale": { "type": "string", "minLength": 2, "maxLength": 16 } }, "required": ["fileName", "pageId", "locale"], "additionalProperties": false }, { "type": "object", "properties": { "projectStamp": { "type": "string", "minLength": 1, "maxLength": 255 }, "compId": { "type": "string", "minLength": 1, "maxLength": 255 }, "locale": { "type": "string", "minLength": 2, "maxLength": 16 } }, "required": ["projectStamp", "compId", "locale"], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Plugin command result", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "versionId": { "type": "string" }, "locale": { "type": "string" }, "translations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string" }, "baseStyle": { "type": "object", "properties": { "fontName": { "type": "object", "properties": { "family": { "type": "string" }, "style": { "type": "string" } }, "required": ["family", "style"], "additionalProperties": false }, "fontSize": { "type": "number" }, "textDecoration": { "type": "string" }, "textCase": { "type": "string" }, "letterSpacing": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": ["value", "unit"], "additionalProperties": false }, "lineHeight": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": ["unit"], "additionalProperties": false }, "fills": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "hyperlink": { "type": ["object", "null"], "additionalProperties": {} } }, "additionalProperties": false }, "styleRuns": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 }, "style": { "type": "object", "properties": { "fontName": { "type": "object", "properties": { "family": { "type": "string" }, "style": { "type": "string" } }, "required": ["family", "style"], "additionalProperties": false }, "fontSize": { "type": "number" }, "textDecoration": { "type": "string" }, "textCase": { "type": "string" }, "letterSpacing": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": ["value", "unit"], "additionalProperties": false }, "lineHeight": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string" } }, "required": ["unit"], "additionalProperties": false }, "fills": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "hyperlink": { "type": ["object", "null"], "additionalProperties": {} } }, "additionalProperties": false } }, "required": ["start", "end", "style"], "additionalProperties": false } } }, "required": ["text", "styleRuns"] } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reason": { "type": "string" }, "detail": { "type": "string" } }, "required": ["key", "reason"] } } }, "required": [ "versionId", "locale", "translations", "warnings" ] }, { "type": "object", "properties": { "versionId": { "type": "string" }, "locale": { "type": "string" }, "translations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string" }, "baseStyle": { "type": "object", "properties": { "font": { "type": "string", "maxLength": 255 }, "fontSize": { "type": "number" }, "fillColor": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "applyFill": { "type": "boolean" }, "fauxBold": { "type": "boolean" }, "fauxItalic": { "type": "boolean" }, "tracking": { "type": "number" }, "applyStroke": { "type": "boolean" }, "strokeColor": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "strokeWidth": { "type": "number" } }, "additionalProperties": false }, "styleRuns": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 }, "style": { "type": "object", "properties": { "font": { "type": "string", "maxLength": 255 }, "fontSize": { "type": "number" }, "fillColor": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "applyFill": { "type": "boolean" }, "fauxBold": { "type": "boolean" }, "fauxItalic": { "type": "boolean" }, "tracking": { "type": "number" }, "applyStroke": { "type": "boolean" }, "strokeColor": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ] }, "strokeWidth": { "type": "number" } }, "additionalProperties": false } }, "required": ["start", "end", "style"], "additionalProperties": false } } }, "required": ["text", "styleRuns"] } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reason": { "type": "string" }, "detail": { "type": "string" } }, "required": ["key", "reason"] } } }, "required": [ "versionId", "locale", "translations", "warnings" ] } ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "423": { "description": "The resource is locked by an operation in progress. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v1/integrations/workspace-plugin/info": { "post": { "operationId": "workspacePluginInfo", "x-internal": true, "summary": "Workspace plugin info", "description": "Run the Google Drive Workspace plugin info command.", "tags": ["Integrations"], "security": [ { "GoogleIdentityToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1, "description": "File ID assigned by Google Drive, found in the Google Docs or Slides URL after /d/. This is not a GT database file ID. May identify a source file or a GT-managed translated copy. Supply hostApp with fileId for file-specific context; omit both to list connected projects." }, "hostApp": { "type": "string", "enum": ["DOCS", "SLIDES"], "description": "Google editor for the file: DOCS for Google Docs or SLIDES for Google Slides. Supply fileId with hostApp for file-specific context." } } } } } }, "responses": { "200": { "description": "Workspace plugin result", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "email": { "type": ["string", "null"] } }, "required": ["email"] }, "supportedLocales": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "orgName": { "type": ["string", "null"] }, "sourceLocale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "currentLocales": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "localeWhitelist": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "integrationConnected": { "type": "boolean" }, "integrationId": { "type": "string" }, "linkedFile": { "type": ["object", "null"], "properties": { "sourceLocale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "required": ["sourceLocale"] }, "translatedCopy": { "type": ["object", "null"], "properties": { "sourceName": { "type": "string" }, "sourceResourceId": { "type": "string" }, "sourceLocale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] }, "targetLocale": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "emoji": { "type": "string" } }, "required": ["code", "name", "emoji"] } }, "required": [ "sourceName", "sourceResourceId", "sourceLocale", "targetLocale" ] } }, "required": [ "id", "name", "orgName", "sourceLocale", "currentLocales", "localeWhitelist", "integrationConnected", "integrationId", "linkedFile", "translatedCopy" ] } } }, "required": ["user", "supportedLocales", "projects"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "502": { "description": "An upstream service failed to complete the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/v2/project/info/{projectId}": { "get": { "operationId": "getProjectInfo", "summary": "Get Project information", "description": "Get a project's ID, name, Organization, locales, and auto-approval setting. No permission is needed beyond access to the project.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "responses": { "200": { "description": "Project information", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "orgId": { "type": "string" }, "defaultLocale": { "type": "string" }, "currentLocales": { "type": "array", "items": { "type": "string" } }, "autoApprove": { "type": "boolean" } }, "required": [ "id", "name", "orgId", "defaultLocale", "currentLocales", "autoApprove" ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] }, "post": { "operationId": "updateProjectInfo", "summary": "Update Project information", "description": "Update a project's default locale or CDN delivery setting. Requires `project:write`. Omitted settings remain unchanged.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultLocale": { "type": "string" }, "cdnEnabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Project settings updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [true] } }, "required": ["success"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/project/jobs/info": { "post": { "operationId": "getTranslationJobInfo", "summary": "Get translation job status", "description": "Get the status of one or more translation or context generation jobs.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jobIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 } }, "required": ["jobIds"] } } } }, "responses": { "200": { "description": "Translation job statuses", "content": { "application/json": { "schema": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["queued"] }, "jobId": { "type": "string" } }, "required": ["status", "jobId"] }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["processing"] }, "jobId": { "type": "string" } }, "required": ["status", "jobId"] }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["failed"] }, "jobId": { "type": "string" }, "error": { "type": "object", "properties": { "message": { "type": ["string", "null"] } }, "required": ["message"] } }, "required": ["status", "jobId", "error"] }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["completed"] }, "jobId": { "type": "string" } }, "required": ["status", "jobId"] }, { "type": "object", "properties": { "status": { "type": "string", "enum": ["unknown"] }, "jobId": { "type": "string" } }, "required": ["status", "jobId"] } ] } } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Translation"] } }, "/v2/project/translations/files/status/{fileId}": { "get": { "operationId": "getTranslationStatus", "summary": "Get translation status for a file", "description": "Return translation progress and availability by locale for one source file, along with its source metadata.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "fileId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "versionId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "branchId", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "responses": { "200": { "description": "Translation status", "content": { "application/json": { "schema": { "type": "object", "properties": { "translations": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string" }, "completedAt": { "type": ["string", "null"], "format": "date-time" }, "approvedAt": { "type": ["string", "null"], "format": "date-time" }, "publishedAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": ["string", "null"], "format": "date-time" }, "updatedAt": { "type": ["string", "null"], "format": "date-time" } }, "required": [ "locale", "completedAt", "approvedAt", "publishedAt", "createdAt", "updatedAt" ] } }, "sourceFile": { "type": "object", "properties": { "id": { "type": "string" }, "branchId": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "fileName": { "type": "string" }, "sourceLocale": { "type": "string" }, "fileFormat": { "$ref": "#/components/schemas/FileFormat" }, "dataFormat": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "locales": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "branchId", "fileId", "versionId", "fileName", "sourceLocale", "fileFormat", "dataFormat", "createdAt", "updatedAt", "locales" ] } }, "required": ["translations", "sourceFile"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/files/diffs": { "post": { "operationId": "submitUserEditDiffs", "summary": "Submit translation diffs", "description": "Overwrite translations with user-provided localized content.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string" }, "diffs": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "minLength": 1 }, "diff": { "type": "string" }, "branchId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "fileId": { "type": "string", "minLength": 1 }, "localContent": { "type": "string" } }, "required": [ "locale", "diff", "versionId", "fileId", "localContent" ] }, "minItems": 1 } }, "required": ["diffs"] } } } }, "responses": { "200": { "description": "Processed user translation edits", "content": { "application/json": { "schema": { "type": "object", "properties": { "filesProcessed": { "type": "integer", "minimum": 0 }, "entriesReceived": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } }, "required": ["filesProcessed", "entriesReceived", "message"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/files/moves": { "post": { "operationId": "processFileMoves", "summary": "Move or rename files", "description": "Clone source files and their translations under new file IDs.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branchId": { "type": "string" }, "moves": { "type": "array", "items": { "type": "object", "properties": { "oldFileId": { "type": "string", "minLength": 1 }, "newFileId": { "type": "string", "minLength": 1 }, "newFileName": { "type": "string", "minLength": 1 } }, "required": ["oldFileId", "newFileId", "newFileName"] } } }, "required": ["moves"] } } } }, "responses": { "200": { "description": "File move results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "oldFileId": { "type": "string" }, "newFileId": { "type": "string" }, "success": { "type": "boolean" }, "newSourceFileId": { "type": "string" }, "clonedTranslationsCount": { "type": "integer" }, "error": { "type": "string" } }, "required": ["oldFileId", "newFileId", "success"] } }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "succeeded": { "type": "integer", "minimum": 0 }, "failed": { "type": "integer", "minimum": 0 } }, "required": ["total", "succeeded", "failed"] } }, "required": ["results"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/files/orphaned": { "post": { "operationId": "getOrphanedFiles", "summary": "Find orphaned files", "description": "Return files on a branch that are not present in the provided file ID list.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branchId": { "type": "string", "minLength": 1 }, "fileIds": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": ["branchId"] } } } }, "responses": { "200": { "description": "Files present on the branch but absent from the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "orphanedFiles": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "versionId": { "type": "string" }, "fileName": { "type": "string" } }, "required": ["fileId", "versionId", "fileName"] } } }, "required": ["orphanedFiles"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/files/info": { "post": { "operationId": "getFileInfo", "summary": "Get file metadata", "description": "Get detailed metadata for specific source and translated files.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceFiles": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "branchId": { "type": "string", "minLength": 1 } }, "required": ["fileId", "versionId", "branchId"] } }, "translatedFiles": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "branchId": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 } }, "required": ["fileId", "versionId", "branchId", "locale"] } } } } } } }, "responses": { "200": { "description": "File information", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceFiles": { "type": "array", "items": { "type": "object", "properties": { "branchId": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "fileName": { "type": "string" }, "fileFormat": { "$ref": "#/components/schemas/FileFormat" }, "dataFormat": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": ["string", "null"], "format": "date-time" }, "locales": { "type": "array", "items": { "type": "string" } }, "sourceLocale": { "type": "string" } }, "required": [ "branchId", "fileId", "versionId", "fileName", "fileFormat", "dataFormat", "createdAt", "updatedAt", "publishedAt", "locales", "sourceLocale" ] } }, "translatedFiles": { "type": "array", "items": { "type": "object", "properties": { "branchId": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "fileFormat": { "$ref": "#/components/schemas/FileFormat" }, "dataFormat": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "approvedAt": { "type": ["string", "null"], "format": "date-time" }, "publishedAt": { "type": ["string", "null"], "format": "date-time" }, "completedAt": { "type": ["string", "null"], "format": "date-time" }, "locale": { "type": "string" } }, "required": [ "branchId", "fileId", "versionId", "fileFormat", "dataFormat", "createdAt", "updatedAt", "approvedAt", "publishedAt", "completedAt", "locale" ] } } }, "required": ["sourceFiles", "translatedFiles"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/files/download": { "post": { "operationId": "downloadFiles", "summary": "Download multiple files", "description": "Download up to 100 source or translated files in one request.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1 }, "branchId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "useLatestAvailableVersion": { "type": "boolean" } }, "required": ["fileId"] }, "minItems": 1, "maxItems": 100 } } } }, "responses": { "200": { "description": "Downloaded files", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "branchId": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "locale": { "type": "string" }, "fileName": { "type": "string" }, "data": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/JsonObject" }, "fileFormat": { "$ref": "#/components/schemas/FileFormat" } }, "required": [ "id", "branchId", "fileId", "versionId", "data", "metadata", "fileFormat" ] } }, "count": { "type": "number" }, "pending": { "type": "array", "items": { "type": "object", "properties": { "branchId": { "type": "string" }, "fileId": { "type": "string" }, "locale": { "type": "string" }, "versionId": { "type": "string" } }, "required": [ "branchId", "fileId", "locale", "versionId" ] } } }, "required": ["files", "count"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/files/download/{fileId}": { "get": { "operationId": "downloadFile", "summary": "Download a single file", "deprecated": true, "description": "Download a single source or translated file. This deprecated endpoint is retained for backward compatibility; new integrations should use `POST /v2/project/files/download`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "fileId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "branchId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "versionId", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "locale", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "responses": { "200": { "description": "Downloaded file", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "425": { "description": "The requested translation has not finished yet. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/files/publish": { "post": { "operationId": "publishFiles", "summary": "Publish or unpublish files", "description": "Publish or unpublish translated files to the CDN. Requires CDN to be enabled.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "branchId": { "type": "string", "minLength": 1 }, "publish": { "type": "boolean" } }, "required": ["fileId", "versionId", "publish"] }, "minItems": 1 } }, "required": ["files"] } } } }, "responses": { "200": { "description": "File publish results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "versionId": { "type": "string" }, "locale": { "type": "string" }, "branchId": { "type": "string" }, "success": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "fileId", "versionId", "branchId", "success" ] } } }, "required": ["results"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/files/upload-files": { "post": { "operationId": "uploadSourceFiles", "summary": "Upload source files", "description": "Upload one or more source files to the project. Max 100 files per request.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "object", "properties": { "content": { "type": "string" }, "fileName": { "type": "string", "minLength": 1 }, "fileFormat": { "type": "string", "enum": [ "GTJSON", "MDX", "JSON", "YAML", "MD", "TS", "JS", "HTML", "TXT", "PO", "POT", "TWILIO_CONTENT_JSON", "LOTTIE", "SVG", "XCSTRINGS", "DOT_STRINGS", "DOT_STRINGSDICT", "ANDROID_STRINGS", "SRT", "RESX" ] }, "dataFormat": { "type": "string" }, "locale": { "type": "string", "minLength": 1 }, "fileId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "branchId": { "type": "string", "minLength": 1 }, "checkedOutBranchId": { "type": "string", "minLength": 1 }, "incomingBranchId": { "type": "string", "minLength": 1 }, "formatMetadata": { "type": "object", "additionalProperties": {} } }, "required": [ "content", "fileName", "fileFormat", "locale" ] } }, "required": ["source"] }, "minItems": 1, "maxItems": 100 }, "sourceLocale": { "type": "string" } }, "required": ["data"] } } } }, "responses": { "201": { "description": "Uploaded source files", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadedFiles": { "type": "array", "items": { "type": "object", "properties": { "branchId": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "fileName": { "type": "string" }, "fileFormat": { "$ref": "#/components/schemas/FileFormat" }, "dataFormat": { "$ref": "#/components/schemas/DataFormat" }, "locale": { "type": "string" } }, "required": [ "branchId", "fileId", "versionId", "fileName", "fileFormat" ] } }, "count": { "type": "number" }, "message": { "type": "string" } }, "required": ["uploadedFiles", "count", "message"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "The server is too busy to process the uploaded files. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/translations/enqueue": { "post": { "operationId": "enqueueFileTranslations", "summary": "Queue files for translation", "description": "Enqueue uploaded source files for background translation. Max 100 files per request. The response shape depends on the requested `gt-api-version`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "branchId": { "type": "string", "minLength": 1 }, "fileId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "fileName": { "type": "string" }, "transformFormat": { "type": "string", "enum": [ "GTJSON", "MDX", "JSON", "YAML", "MD", "TS", "JS", "HTML", "TXT", "PO", "POT", "TWILIO_CONTENT_JSON", "LOTTIE", "SVG", "XCSTRINGS", "DOT_STRINGS", "DOT_STRINGSDICT", "ANDROID_STRINGS", "SRT", "RESX" ] } }, "required": ["fileId", "versionId"] }, "minItems": 1, "maxItems": 100 }, "targetLocales": { "type": "array", "items": { "type": "string" } }, "sourceLocale": { "type": "string" }, "force": { "type": "boolean", "default": false }, "modelProvider": { "$ref": "#/components/schemas/ModelProvider" }, "publish": { "type": "boolean" } }, "required": ["files"] } } } }, "responses": { "200": { "description": "Enqueued translations. Shape depends on gt-api-version (legacy before 2025-11-03.v1).", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "jobData": { "type": "object", "additionalProperties": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["file_translation"] }, "sourceFileId": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "branchId": { "type": "string" }, "targetLocale": { "type": "string" }, "projectId": { "type": "string" }, "orgId": { "type": "string" }, "force": { "type": "boolean" }, "outputFileFormat": { "$ref": "#/components/schemas/FileFormat" }, "modelProvider": { "$ref": "#/components/schemas/ModelProvider" }, "glossaryRetranslate": { "type": "boolean" }, "changedGlossaryTerms": { "type": "array", "items": { "type": "string" } }, "onComplete": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["google_drive_apply"] }, "userId": { "type": "string" } }, "required": ["kind"] } }, "required": [ "sourceFileId", "fileId", "versionId", "branchId", "targetLocale", "projectId", "orgId", "force" ] } }, "locales": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": ["jobData", "locales", "message"] }, { "type": "object", "properties": { "translations": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string" }, "metadata": {}, "fileId": { "type": "string" }, "fileName": { "type": "string" }, "versionId": { "type": "string" }, "branchId": { "type": "string" }, "id": { "type": "string" }, "isReady": { "type": "boolean" }, "downloadUrl": { "type": "string" } }, "required": [ "locale", "fileId", "fileName", "versionId", "branchId", "id", "isReady", "downloadUrl" ] } }, "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "fileName": { "type": "string" }, "versionId": { "type": "string" } }, "required": ["fileName", "versionId"] } }, "locales": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": ["translations", "data", "locales", "message"] } ] } } } }, "400": { "description": "Invalid request or missing source files", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "error": { "type": "string" }, "missing": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "versionId": { "type": "string" } }, "required": ["fileId", "versionId"] } }, "count": { "type": "number" } }, "required": ["error", "missing", "count"] } ] } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "402": { "description": "The organization's billing account is blocked, or its plan usage limit, monthly spend limit, or credit balance does not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Translation"] } }, "/v2/project/files/upload-translations": { "post": { "operationId": "uploadTranslations", "summary": "Upload translated files", "description": "Upload translated files linked to their source files. Max 100 files per request.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "object", "properties": { "content": { "type": "string" }, "fileName": { "type": "string", "minLength": 1 }, "fileFormat": { "type": "string", "enum": [ "GTJSON", "MDX", "JSON", "YAML", "MD", "TS", "JS", "HTML", "TXT", "PO", "POT", "TWILIO_CONTENT_JSON", "LOTTIE", "SVG", "XCSTRINGS", "DOT_STRINGS", "DOT_STRINGSDICT", "ANDROID_STRINGS", "SRT", "RESX" ] }, "dataFormat": { "type": "string" }, "locale": { "type": "string", "minLength": 1 }, "fileId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "branchId": { "type": "string", "minLength": 1 }, "checkedOutBranchId": { "type": "string", "minLength": 1 }, "incomingBranchId": { "type": "string", "minLength": 1 }, "formatMetadata": { "type": "object", "additionalProperties": {} } }, "required": [ "content", "fileName", "fileFormat", "locale" ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string" }, "fileName": { "type": "string", "minLength": 1 }, "fileFormat": { "type": "string", "enum": [ "GTJSON", "MDX", "JSON", "YAML", "MD", "TS", "JS", "HTML", "TXT", "PO", "POT", "TWILIO_CONTENT_JSON", "LOTTIE", "SVG", "XCSTRINGS", "DOT_STRINGS", "DOT_STRINGSDICT", "ANDROID_STRINGS", "SRT", "RESX" ] }, "dataFormat": { "type": "string" }, "locale": { "type": "string", "minLength": 1 }, "transformFormat": { "type": "string", "enum": [ "GTJSON", "MDX", "JSON", "YAML", "MD", "TS", "JS", "HTML", "TXT", "PO", "POT", "TWILIO_CONTENT_JSON", "LOTTIE", "SVG", "XCSTRINGS", "DOT_STRINGS", "DOT_STRINGSDICT", "ANDROID_STRINGS", "SRT", "RESX" ] } }, "required": [ "content", "fileName", "fileFormat", "locale" ] }, "minItems": 1 } }, "required": ["source", "translations"] }, "minItems": 1, "maxItems": 100 }, "sourceLocale": { "type": "string" } }, "required": ["data"] } } } }, "responses": { "201": { "description": "Uploaded translation files", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadedFiles": { "type": "array", "items": { "type": "object", "properties": { "branchId": { "type": "string" }, "fileId": { "type": "string" }, "versionId": { "type": "string" }, "fileName": { "type": "string" }, "fileFormat": { "$ref": "#/components/schemas/FileFormat" }, "dataFormat": { "$ref": "#/components/schemas/DataFormat" }, "locale": { "type": "string" } }, "required": [ "branchId", "fileId", "versionId", "fileName", "fileFormat" ] } }, "count": { "type": "number" }, "message": { "type": "string" } }, "required": ["uploadedFiles", "count", "message"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "503": { "description": "The server is too busy to process the uploaded files. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Files"] } }, "/v2/project/branches/info": { "post": { "operationId": "getBranchInfo", "summary": "Get branch information", "description": "Return the Project's default branch and any branches requested by name.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branchNames": { "type": "array", "items": { "type": "string" }, "default": [] } } } } } }, "responses": { "200": { "description": "Branch information", "content": { "application/json": { "schema": { "type": "object", "properties": { "branches": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } }, "defaultBranch": { "allOf": [ { "$ref": "#/components/schemas/Branch" }, { "type": ["object", "null"] } ] } }, "required": ["branches", "defaultBranch"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/project/branches/create": { "post": { "operationId": "createBranch", "summary": "Create a branch", "description": "Create a new branch, or rename and confirm the default branch.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branchName": { "type": "string", "minLength": 1 }, "defaultBranch": { "type": "boolean", "default": false } }, "required": ["branchName"] } } } }, "responses": { "200": { "description": "Created or existing branch", "content": { "application/json": { "schema": { "type": "object", "properties": { "branch": { "$ref": "#/components/schemas/Branch" } }, "required": ["branch"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/project/tags/create": { "post": { "operationId": "createTag", "summary": "Create or update a tag", "description": "Create or update a tag for a set of file versions.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tagId": { "type": "string", "minLength": 1, "maxLength": 255 }, "files": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "branchId": { "type": "string", "minLength": 1 } }, "required": ["fileId", "versionId", "branchId"] }, "minItems": 1 }, "message": { "type": "string", "maxLength": 255 } }, "required": ["tagId", "files"] } } } }, "responses": { "200": { "description": "Created or updated file tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "object", "properties": { "id": { "type": "string" }, "tagId": { "type": "string" }, "message": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "tagId", "message", "createdAt", "updatedAt" ] } }, "required": ["tag"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/project/assets": { "post": { "operationId": "uploadAssets", "summary": "Upload Project assets", "description": "Upload OpenType or TrueType fonts for Lottie translations across your Organization. Uploading the same font family, weight, and italic style replaces the existing font. You can safely retry the full upload after a `500` response.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "assetType": { "type": "string", "enum": ["FONT"] }, "content": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "\\.([tT][tT][fF]|[oO][tT][fF])$" }, "family": { "type": "string", "minLength": 1, "maxLength": 255 }, "style": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": ["assetType", "content", "fileName"] }, "minItems": 1, "maxItems": 50 } }, "required": ["assets"] } } } }, "responses": { "201": { "description": "Uploaded assets", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "assetKey": { "type": "string" }, "fileName": { "type": "string" } }, "required": ["id", "assetKey", "fileName"] } }, "count": { "type": "integer", "minimum": 0 } }, "required": ["assets", "count"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/translate": { "post": { "operationId": "translate", "summary": "Translate content at runtime", "description": "Translate strings, structured content, or Markdown and MDX documents. Send documents as strings with `fileFormat` set to `MD` or `MDX`. Requires `project:translations:generate`. Existing development API keys are also accepted.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeTranslationRequest" } } } }, "responses": { "200": { "description": "All translations were served from cache", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeTranslationResponse" } } } }, "201": { "description": "Translations completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeTranslationResponse" } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "402": { "description": "The organization's billing account is blocked, or its plan usage limit, monthly spend limit, or credit balance does not cover this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Translation"] } }, "/v2/projects/{projectId}/api-keys": { "post": { "operationId": "createProjectApiKey", "summary": "Create a Project API Key", "description": "Create a project API key. Requires `project:api_keys:write`; project keys cannot create other keys. If you cannot grant a selected permission, the request returns `403` without creating a key. Each successful request creates a new key. Store the returned secret securely.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "projectId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Key name, 1–255 characters after trimming." }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectApiKeyPermission" }, "minItems": 1, "description": "Project permissions to grant. Select at least one, or omit to grant all project permissions you can delegate. You must hold every selected permission. Duplicates are ignored. Write permissions do not include Read." }, "type": { "type": "string", "enum": ["production", "development"], "deprecated": true, "description": "Ignored. All new keys are project-scoped API keys for any environment." } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Project API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string" }, "projectId": { "type": "string" }, "type": { "type": "string", "enum": ["production"], "deprecated": true, "description": "Compatibility field. All project API keys work in any environment." } }, "required": ["id", "name", "key", "projectId", "type"] } }, "required": ["apiKey"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/projects": { "get": { "operationId": "listProjects", "summary": "List Projects", "description": "List projects you are a member of, or the projects your API key is bound to, ordered by ID. No permission or `gt-project-id` header is needed. Omit `cursor` for the first page. When the response's `nextCursor` is a string, pass it as `cursor` to fetch the next page; when it is `null`, there are no more results.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The nextCursor from the previous page. Omit for the first page." }, "required": false, "description": "The nextCursor from the previous page. Omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of items to return, 1–100. Defaults to 50." }, "required": false, "description": "Maximum number of items to return, 1–100. Defaults to 50.", "name": "limit", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Page of Projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "orgId": { "type": "string" }, "orgName": { "type": "string" } }, "required": ["id", "name", "orgId", "orgName"] } }, "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; `null` when there are no more items. Pages are read independently, so items changed between requests may be missed or repeated." } }, "required": ["items", "nextCursor"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/project/setup/generate": { "post": { "operationId": "generateProjectContext", "summary": "Generate translation context", "description": "Generate glossaries and translation instructions for the project.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" }, { "schema": { "type": "string", "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project." }, "required": false, "description": "Target project ID when no project ID is present in the path. Project API keys default to their bound project. If supplied, the header must match both the path target and the key’s bound project.", "name": "gt-project-id", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "branchId": { "type": "string", "minLength": 1 }, "fileId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": ["fileId", "versionId"] }, "minItems": 1 }, "locales": { "type": "array", "items": { "type": "string" } }, "force": { "type": "boolean", "default": false } }, "required": ["files"] } } } }, "responses": { "200": { "description": "Context generation status", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": ["completed"] } }, "required": ["status"] }, { "type": "object", "properties": { "setupJobId": { "type": "string" }, "status": { "type": "string", "enum": ["queued"] } }, "required": ["setupJobId", "status"] } ] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context"] } }, "/v2/projects/{projectId}/context-groups": { "get": { "operationId": "listProjectContextGroups", "summary": "List project context groups", "description": "Lists the groups assigned to the project, in priority order. Requires `org:context:read`. Omit `cursor` for the first page. When the response's `nextCursor` is a string, pass it as `cursor` to fetch the next page; when it is `null`, there are no more results.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Project ID." }, "required": true, "description": "Project ID.", "name": "projectId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The nextCursor from the previous page. Omit for the first page." }, "required": false, "description": "The nextCursor from the previous page. Omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of items to return, 1–100. Defaults to 50." }, "required": false, "description": "Maximum number of items to return, 1–100. Defaults to 50.", "name": "limit", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Page of project context groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string" }, "groupName": { "type": "string" }, "priority": { "type": "integer", "description": "Lower values take precedence for duplicate terms." } }, "required": ["groupId", "groupName", "priority"] } }, "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; `null` when there are no more items. Pages are read independently, so items changed between requests may be missed or repeated." } }, "required": ["items", "nextCursor"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/projects/{projectId}/context-groups/{groupId}": { "get": { "operationId": "getProjectContextGroup", "summary": "Get a project context group", "description": "Gets one assignment: the group's ID, name and priority. Requires `org:context:read`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Project ID." }, "required": true, "description": "Project ID.", "name": "projectId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Project assignment", "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "type": "string" }, "groupName": { "type": "string" }, "priority": { "type": "integer", "description": "Lower values take precedence for duplicate terms." } }, "required": ["groupId", "groupName", "priority"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "put": { "operationId": "assignContextGroup", "summary": "Assign a context group", "description": "Assigns the group to the project at the lowest priority (201). If it's already assigned, nothing changes (200), and repeating it never moves a group that was reordered. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Project ID." }, "required": true, "description": "Project ID.", "name": "projectId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Already assigned", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] }, "created": { "type": "boolean", "description": "False when the group was already assigned; nothing changed." } }, "required": ["committed", "created"] } } } }, "201": { "description": "Context group assigned", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] }, "created": { "type": "boolean", "description": "False when the group was already assigned; nothing changed." } }, "required": ["committed", "created"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "delete": { "operationId": "unassignContextGroup", "summary": "Unassign a context group", "description": "Removes the assignment and keeps the group and its content. Does nothing if the group isn't assigned. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Project ID." }, "required": true, "description": "Project ID.", "name": "projectId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Assignment removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "patch": { "operationId": "reorderContextGroup", "summary": "Reorder a context group", "description": "Moves the assigned group to a new zero-based position. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Project ID." }, "required": true, "description": "Project ID.", "name": "projectId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetIndex": { "type": "integer", "description": "Zero-based position; out-of-range values move the group to the first or last position." } }, "required": ["targetIndex"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Assignments reordered", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/orgs": { "get": { "operationId": "listOrgs", "summary": "List Organizations", "description": "List Organizations you can access, ordered by ID. Organization and Project keys each return only their own Organization; user tokens return every Organization the user belongs to. No project ID, permission, or token scope is required. Omit `cursor` for the first page. When the response's `nextCursor` is a string, pass it as `cursor` to fetch the next page; when it is `null`, there are no more results.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The nextCursor from the previous page. Omit for the first page." }, "required": false, "description": "The nextCursor from the previous page. Omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of items to return, 1–100. Defaults to 50." }, "required": false, "description": "Maximum number of items to return, 1–100. Defaults to 50.", "name": "limit", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Page of Organizations", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] } }, "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; `null` when there are no more items. Pages are read independently, so items changed between requests may be missed or repeated." } }, "required": ["items", "nextCursor"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/orgs/{orgId}/projects": { "post": { "operationId": "createProject", "summary": "Create a Project", "description": "Create a project in the specified Organization. Requires `org:projects:create`. Returns `409` if your plan's project limit has been reached. Each successful request creates a new project.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "required": true, "name": "orgId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Trimmed Project name, 1–64 characters. Accepts ASCII letters, digits, spaces, dashes, underscores, apostrophes, parentheses, and periods." }, "defaultLocale": { "type": "string", "description": "Source locale for the project." }, "cdnEnabled": { "type": "boolean", "description": "Enable CDN delivery. Defaults to false when omitted." } }, "required": ["name", "defaultLocale"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "orgId": { "type": "string" }, "defaultLocale": { "type": "string" } }, "required": ["id", "name", "orgId", "defaultLocale"] } }, "required": ["project"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Project"] } }, "/v2/orgs/{orgId}/context-groups": { "get": { "operationId": "listContextGroups", "summary": "List context groups", "description": "Lists the org's groups, ordered by ID. Requires `org:context:read`. Omit `cursor` for the first page. When the response's `nextCursor` is a string, pass it as `cursor` to fetch the next page; when it is `null`, there are no more results.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Organization ID." }, "required": true, "description": "Organization ID.", "name": "orgId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The nextCursor from the previous page. Omit for the first page." }, "required": false, "description": "The nextCursor from the previous page. Omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of items to return, 1–100. Defaults to 50." }, "required": false, "description": "Maximum number of items to return, 1–100. Defaults to 50.", "name": "limit", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Page of context groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContextGroup" } }, "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; `null` when there are no more items. Pages are read independently, so items changed between requests may be missed or repeated." } }, "required": ["items", "nextCursor"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "post": { "operationId": "createContextGroup", "summary": "Create a context group", "description": "Creates an empty, unassigned group. Each call creates a new one. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Organization ID." }, "required": true, "description": "Organization ID.", "name": "orgId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Group name, 1–255 characters." } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "201": { "description": "Context group created", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] }, "groupId": { "type": "string" } }, "required": ["committed", "groupId"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}": { "get": { "operationId": "getContextGroup", "summary": "Get a context group", "description": "Gets the group's ID and name. Requires `org:context:read`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Context group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextGroup" } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "patch": { "operationId": "updateContextGroup", "summary": "Update a context group", "description": "Renames the group. The name is the only editable field. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New group name, 1–255 characters." } }, "required": ["name"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Context group updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "delete": { "operationId": "deleteContextGroup", "summary": "Delete a context group", "description": "Deletes the group along with all its terms, custom prompts and project assignments. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Context group deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}/glossary": { "get": { "operationId": "listContextGlossary", "summary": "List glossary terms", "description": "Lists terms by ID, without translations. `keyword` is optional and matches the stored keyword exactly (case-sensitive), so it returns at most one term. Requires `org:context:read`. Omit `cursor` for the first page. When the response's `nextCursor` is a string, pass it as `cursor` to fetch the next page; when it is `null`, there are no more results.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The nextCursor from the previous page. Omit for the first page." }, "required": false, "description": "The nextCursor from the previous page. Omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of items to return, 1–100. Defaults to 50." }, "required": false, "description": "Maximum number of items to return, 1–100. Defaults to 50.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Only the term whose stored keyword is exactly this value (case-sensitive)." }, "required": false, "description": "Only the term whose stored keyword is exactly this value (case-sensitive).", "name": "keyword", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Page of glossary terms", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "keyword": { "type": "string" }, "definition": { "type": ["string", "null"] }, "userDefined": { "type": "boolean" } }, "required": [ "id", "keyword", "definition", "userDefined" ] } }, "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; `null` when there are no more items. Pages are read independently, so items changed between requests may be missed or repeated." } }, "required": ["items", "nextCursor"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "post": { "operationId": "upsertContextGlossary", "summary": "Upsert glossary terms", "description": "Creates or updates 1–100 terms (`{ entries: [...] }`; send one term as a one-item array), matched by keyword, in one atomic batch. An absent field keeps its stored value. `null` clears a nullable field or removes a map entry; other fields reject `null`. In batches and imports, items match stored items by natural key, stored items absent from the batch are untouched, and nothing else is deleted. A blank CSV cell counts as absent. Repeating a keyword within one batch rejects the whole batch (400). Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "userDefined": { "type": "boolean" }, "definition": { "type": ["string", "null"], "description": "null clears the definition." }, "translations": { "type": "object", "additionalProperties": { "type": ["object", "null"], "properties": { "translation": { "type": "string" }, "userDefined": { "type": "boolean" } }, "required": ["translation"], "additionalProperties": false }, "description": "Translations by locale; null for a locale deletes its translation." } }, "required": ["keyword"], "additionalProperties": false }, "minItems": 1, "maxItems": 100, "description": "1–100 terms, matched by keyword; a keyword may appear once." } }, "required": ["entries"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Glossary terms written", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] }, "counts": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" } }, "required": ["created", "updated", "unchanged"] } }, "required": ["committed", "counts"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}/glossary/{entryId}": { "get": { "operationId": "getContextGlossaryEntry", "summary": "Get a glossary term", "description": "Gets a term by ID: its keyword and definition. Translations are listed separately. Requires `org:context:read`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Glossary term ID." }, "required": true, "description": "Glossary term ID.", "name": "entryId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Glossary term", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "keyword": { "type": "string" }, "definition": { "type": ["string", "null"] } }, "required": ["id", "keyword", "definition"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "patch": { "operationId": "updateContextGlossaryEntry", "summary": "Update a glossary term", "description": "Updates the term's keyword or definition. An absent field keeps its stored value. `null` clears a nullable field or removes a map entry; other fields reject `null`. In batches and imports, items match stored items by natural key, stored items absent from the batch are untouched, and nothing else is deleted. A blank CSV cell counts as absent. The term ID and translations are kept when the keyword is renamed. Renaming to a keyword another term already has returns 409. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Glossary term ID." }, "required": true, "description": "Glossary term ID.", "name": "entryId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string" }, "definition": { "type": ["string", "null"], "description": "null clears the definition." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Glossary term updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "delete": { "operationId": "deleteContextGlossaryEntry", "summary": "Delete a glossary term", "description": "Deletes a term and all of its translations. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Glossary term ID." }, "required": true, "description": "Glossary term ID.", "name": "entryId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Glossary term deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}/glossary/{entryId}/translations": { "get": { "operationId": "listContextGlossaryTranslations", "summary": "List term translations", "description": "Lists a term's translations by ID. Requires `org:context:read`. Omit `cursor` for the first page. When the response's `nextCursor` is a string, pass it as `cursor` to fetch the next page; when it is `null`, there are no more results.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Glossary term ID." }, "required": true, "description": "Glossary term ID.", "name": "entryId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The nextCursor from the previous page. Omit for the first page." }, "required": false, "description": "The nextCursor from the previous page. Omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of items to return, 1–100. Defaults to 50." }, "required": false, "description": "Maximum number of items to return, 1–100. Defaults to 50.", "name": "limit", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Page of term translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "locale": { "type": "string" }, "translation": { "type": "string" }, "userDefined": { "type": "boolean" } }, "required": [ "id", "locale", "translation", "userDefined" ] } }, "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; `null` when there are no more items. Pages are read independently, so items changed between requests may be missed or repeated." } }, "required": ["items", "nextCursor"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}/glossary/{entryId}/translations/{locale}": { "put": { "operationId": "setContextGlossaryTranslation", "summary": "Set a term translation", "description": "Creates or replaces one locale's translation (201 when created, 200 when replaced). Keeps the term and its other translations. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Glossary term ID." }, "required": true, "description": "Glossary term ID.", "name": "entryId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Translation locale." }, "required": true, "description": "Translation locale.", "name": "locale", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "translation": { "type": "string", "description": "The locale's translation of the term." } }, "required": ["translation"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Translation replaced", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] }, "outcome": { "type": "string", "enum": ["created", "updated", "unchanged"] } }, "required": ["committed", "outcome"] } } } }, "201": { "description": "Translation created", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] }, "outcome": { "type": "string", "enum": ["created", "updated", "unchanged"] } }, "required": ["committed", "outcome"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "delete": { "operationId": "deleteContextGlossaryTranslation", "summary": "Delete a term translation", "description": "Deletes one locale's translation and keeps the term and its other translations. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Glossary term ID." }, "required": true, "description": "Glossary term ID.", "name": "entryId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Translation locale." }, "required": true, "description": "Translation locale.", "name": "locale", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Translation deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}/custom-prompts": { "get": { "operationId": "listContextCustomPrompts", "summary": "List custom prompts", "description": "Lists prompts by ID. A null locale means the prompt applies to every locale. Requires `org:context:read`. Omit `cursor` for the first page. When the response's `nextCursor` is a string, pass it as `cursor` to fetch the next page; when it is `null`, there are no more results.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The nextCursor from the previous page. Omit for the first page." }, "required": false, "description": "The nextCursor from the previous page. Omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of items to return, 1–100. Defaults to 50." }, "required": false, "description": "Maximum number of items to return, 1–100. Defaults to 50.", "name": "limit", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Page of custom prompts", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "locale": { "type": ["string", "null"], "description": "Locale the prompt applies to; null applies to all locales." }, "value": { "type": "string" } }, "required": [ "id", "name", "description", "locale", "value" ] } }, "nextCursor": { "type": ["string", "null"], "description": "Opaque cursor for the next page; `null` when there are no more items. Pages are read independently, so items changed between requests may be missed or repeated." } }, "required": ["items", "nextCursor"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "post": { "operationId": "upsertContextCustomPrompts", "summary": "Upsert custom prompts", "description": "Creates or updates 1–100 prompts (`{ customPrompts: [...] }`), each matched by name and locale, in one atomic batch. An absent field keeps its stored value. `null` clears a nullable field or removes a map entry; other fields reject `null`. In batches and imports, items match stored items by natural key, stored items absent from the batch are untouched, and nothing else is deleted. A blank CSV cell counts as absent. Repeating a name and locale within one batch rejects the whole batch (400). Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customPrompts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "locale": { "type": ["string", "null"], "description": "Locale the prompt applies to; null applies it to every locale." }, "value": { "type": "string" }, "description": { "type": ["string", "null"], "description": "null clears the description." } }, "required": ["name", "locale", "value"], "additionalProperties": false }, "minItems": 1, "maxItems": 100, "description": "1–100 prompts, matched by name and locale; a name and locale may appear once." } }, "required": ["customPrompts"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Custom prompts written", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] }, "counts": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" } }, "required": ["created", "updated", "unchanged"] } }, "required": ["committed", "counts"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}/custom-prompts/{customPromptId}": { "patch": { "operationId": "updateContextCustomPrompt", "summary": "Update a custom prompt", "description": "Updates a prompt by ID. An absent field keeps its stored value. `null` clears a nullable field or removes a map entry; other fields reject `null`. In batches and imports, items match stored items by natural key, stored items absent from the batch are untouched, and nothing else is deleted. A blank CSV cell counts as absent. Returns 409 if another prompt already has the resulting name and locale. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Custom prompt ID." }, "required": true, "description": "Custom prompt ID.", "name": "customPromptId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "locale": { "type": ["string", "null"], "description": "Locale the prompt applies to; null applies it to every locale." }, "value": { "type": "string" }, "description": { "type": ["string", "null"], "description": "null clears the description." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Custom prompt updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "409": { "description": "The request conflicts with existing data or the current state of the project or organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] }, "delete": { "operationId": "deleteContextCustomPrompt", "summary": "Delete a custom prompt", "description": "Deletes a prompt. Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Custom prompt ID." }, "required": true, "description": "Custom prompt ID.", "name": "customPromptId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Custom prompt deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] } }, "required": ["committed"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}/import": { "post": { "operationId": "importContextContent", "summary": "Import context content", "description": "Merges one JSON or CSV transfer document of terms and custom prompts into the group as one atomic batch. The whole document is validated before anything is written. An absent field keeps its stored value. `null` clears a nullable field or removes a map entry; other fields reject `null`. In batches and imports, items match stored items by natural key, stored items absent from the batch are untouched, and nothing else is deleted. A blank CSV cell counts as absent. In CSV, a blank prompt locale means every locale, and the term, prompt name and prompt text can't be blank (400). Requires `org:context:write`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": ["json", "csv"], "description": "Transfer document format." }, "content": { "type": "string", "description": "One JSON or CSV transfer document, up to 1 MiB as a JSON string, so escaped quotes and line breaks count toward the limit. An exported page always fits. It is validated in full before anything is written. A JSON document has the shape `{ glossary: [{ keyword, definition?, translations?: { : { translation } | null } }], customPrompts: [{ name, locale, value, description? }] }`; definition, locale and description may be null. An absent field keeps its stored value. `null` clears a nullable field or removes a map entry; other fields reject `null`. In batches and imports, items match stored items by natural key, stored items absent from the batch are untouched, and nothing else is deleted. A blank CSV cell counts as absent." } }, "required": ["format", "content"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Content imported", "content": { "application/json": { "schema": { "type": "object", "properties": { "committed": { "type": "boolean", "enum": [true] }, "glossary": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" } }, "required": ["created", "updated", "unchanged"] }, "customPrompts": { "type": "object", "properties": { "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" } }, "required": ["created", "updated", "unchanged"] } }, "required": ["committed", "glossary", "customPrompts"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/v2/context-groups/{groupId}/export": { "get": { "operationId": "exportContextContent", "summary": "Export context content", "description": "Exports the group's terms and custom prompts as paged transfer documents. Each page can be re-imported as one batch. Pass `nextCursor` as `cursor` until it is `null`. Pages aren't a snapshot, so changes made mid-export may be missed or included. Requires `org:context:read`.", "security": [ { "BearerAuth": [] }, { "UserBearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Context group ID." }, "required": true, "description": "Context group ID.", "name": "groupId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The nextCursor from the previous page. Omit for the first page." }, "required": false, "description": "The nextCursor from the previous page. Omit for the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "Maximum number of items to return, 1–100. Defaults to 50." }, "required": false, "description": "Maximum number of items to return, 1–100. Defaults to 50.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": ["json", "csv"], "description": "Transfer document format." }, "required": true, "description": "Transfer document format.", "name": "format", "in": "query" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "Page of exported content", "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": ["json", "csv"], "description": "Transfer document format." }, "content": { "type": "string", "description": "One self-contained transfer document that can be imported as a single batch." }, "nextCursor": { "type": ["string", "null"], "description": "Pass as cursor for the next page; null ends the export." } }, "required": ["format", "content", "nextCursor"] } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "The caller is authenticated but not allowed to perform this operation or access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } }, "tags": ["Context Management"] } }, "/cli/wizard/session": { "post": { "operationId": "createCliWizardSession", "x-internal": true, "deprecated": true, "summary": "Create a CLI wizard session", "description": "Create a temporary session for CLI browser authentication.", "tags": ["CLI Wizard"], "parameters": [ { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCliWizardSessionRequest" } } } }, "responses": { "200": { "description": "CLI wizard session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCliWizardSessionResponse" } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "415": { "description": "The request body's Content-Type is missing or not supported. Send the body as application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/cli/wizard/{sessionId}": { "get": { "operationId": "getCliWizardSession", "x-internal": true, "deprecated": true, "summary": "Get a CLI wizard session", "description": "Get credentials for a completed CLI wizard session or its current waiting status.", "tags": ["CLI Wizard"], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "sessionId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "CLI wizard session credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliWizardSessionReadyResponse" } } } }, "202": { "description": "CLI wizard session is waiting for sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliWizardSessionWaitingResponse" } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } }, "delete": { "operationId": "deleteCliWizardSession", "x-internal": true, "deprecated": true, "summary": "Delete a CLI wizard session", "description": "Delete a completed or abandoned CLI wizard session.", "tags": ["CLI Wizard"], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "sessionId", "in": "path" }, { "schema": { "$ref": "#/components/schemas/ApiVersion" }, "required": false, "description": "API contract version. Defaults to the oldest supported version.", "name": "gt-api-version", "in": "header" } ], "responses": { "200": { "description": "CLI wizard session deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCliWizardSessionResponse" } } } }, "400": { "description": "The request is malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "The request, or the data it would return, exceeds a size or item limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "429": { "description": "Too many requests. The rate limit was exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }, "text/html": { "schema": { "type": "string" } } } } } } } }, "webhooks": {} }