{ "openapi": "3.1.0", "info": { "title": "AI Glot API", "version": "1.0.0", "description": "The AI Glot developer platform. Read your workspace, credits, usage and translations, and manage glossaries — from a script, a terminal, or an AI agent.\n\nNothing in this version starts engine work or spends a credit; uploads and batch creation arrive with the multi-format engine. Discover that from `capabilities.batch_creation` on `GET /v1/account` rather than from a version number.", "contact": { "name": "AI Glot", "url": "https://ai-glot.com" } }, "servers": [ { "url": "https://api.ai-glot.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key (`aig_live_…`) created in the workspace settings, or an OAuth access token. Never place a credential in a URL or query string." } }, "schemas": { "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "docs_url": { "type": "string" } }, "required": [ "type", "code", "message", "docs_url" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false } }, "responses": { "Error400": { "description": "Possible codes: invalid_request, unknown_field, invalid_parameter, invalid_cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Possible codes: authentication_required, invalid_api_key, api_key_expired, api_key_revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Possible codes: insufficient_scope, feature_not_available, admin_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Possible codes: batch_not_found, glossary_not_found, resource_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "Possible codes: glossary_already_exists, result_not_ready, batch_not_editable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error413": { "description": "Possible codes: request_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error422": { "description": "Possible codes: language_not_supported, invalid_language_pair, glossary_term_limit_reached, glossary_limit_reached, invalid_glossary_terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Possible codes: rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error500": { "description": "Possible codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Possible codes: service_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "x-scopes": { "account:read": "See your workspace, plan, and credit balance.", "usage:read": "See your credit usage over time.", "batches:read": "See your translations and download their results.", "batches:write": "Rename and archive your translations, and stop one that is running. Renaming and archiving work today; stopping a running translation is not available yet.", "batches:create": "Start a new translation, and approve one after its review step. Both spend your workspace credits. Not available yet.", "files:write": "Upload files to your workspace so they can be translated. Not available yet.", "glossaries:read": "See your glossaries and their terms.", "glossaries:write": "Create, edit, and delete your glossaries.", "webhooks:write": "Create, edit, and delete the webhooks that notify your systems when work finishes. Not available yet." }, "x-error-codes": [ { "code": "authentication_required", "status": 401, "type": "authentication_error", "docs_url": "https://ai-glot.com/docs/api/errors#authentication_required" }, { "code": "invalid_api_key", "status": 401, "type": "authentication_error", "docs_url": "https://ai-glot.com/docs/api/errors#invalid_api_key" }, { "code": "api_key_expired", "status": 401, "type": "authentication_error", "docs_url": "https://ai-glot.com/docs/api/errors#api_key_expired" }, { "code": "api_key_revoked", "status": 401, "type": "authentication_error", "docs_url": "https://ai-glot.com/docs/api/errors#api_key_revoked" }, { "code": "insufficient_scope", "status": 403, "type": "permission_error", "docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope" }, { "code": "feature_not_available", "status": 403, "type": "permission_error", "docs_url": "https://ai-glot.com/docs/api/errors#feature_not_available" }, { "code": "admin_required", "status": 403, "type": "permission_error", "docs_url": "https://ai-glot.com/docs/api/errors#admin_required" }, { "code": "invalid_request", "status": 400, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#invalid_request" }, { "code": "unknown_field", "status": 400, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#unknown_field" }, { "code": "invalid_parameter", "status": 400, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#invalid_parameter" }, { "code": "invalid_cursor", "status": 400, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#invalid_cursor" }, { "code": "request_too_large", "status": 413, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#request_too_large" }, { "code": "batch_not_found", "status": 404, "type": "not_found_error", "docs_url": "https://ai-glot.com/docs/api/errors#batch_not_found" }, { "code": "glossary_not_found", "status": 404, "type": "not_found_error", "docs_url": "https://ai-glot.com/docs/api/errors#glossary_not_found" }, { "code": "resource_not_found", "status": 404, "type": "not_found_error", "docs_url": "https://ai-glot.com/docs/api/errors#resource_not_found" }, { "code": "glossary_already_exists", "status": 409, "type": "conflict_error", "docs_url": "https://ai-glot.com/docs/api/errors#glossary_already_exists" }, { "code": "result_not_ready", "status": 409, "type": "conflict_error", "docs_url": "https://ai-glot.com/docs/api/errors#result_not_ready" }, { "code": "batch_not_editable", "status": 409, "type": "conflict_error", "docs_url": "https://ai-glot.com/docs/api/errors#batch_not_editable" }, { "code": "language_not_supported", "status": 422, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#language_not_supported" }, { "code": "invalid_language_pair", "status": 422, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#invalid_language_pair" }, { "code": "glossary_term_limit_reached", "status": 422, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#glossary_term_limit_reached" }, { "code": "glossary_limit_reached", "status": 422, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#glossary_limit_reached" }, { "code": "invalid_glossary_terms", "status": 422, "type": "invalid_request_error", "docs_url": "https://ai-glot.com/docs/api/errors#invalid_glossary_terms" }, { "code": "rate_limited", "status": 429, "type": "rate_limit_error", "docs_url": "https://ai-glot.com/docs/api/errors#rate_limited" }, { "code": "internal_error", "status": 500, "type": "api_error", "docs_url": "https://ai-glot.com/docs/api/errors#internal_error" }, { "code": "service_unavailable", "status": 503, "type": "api_error", "docs_url": "https://ai-glot.com/docs/api/errors#service_unavailable" } ], "paths": { "/v1/account": { "get": { "operationId": "getAccount", "summary": "Retrieve the authenticated workspace", "description": "Identity, plan, entitlements, and the credential making the call. Call this first: one request tells you everything you are allowed to do, including whether batch creation exists yet (`capabilities.batch_creation`).", "tags": [ "account" ], "parameters": [], "security": [ { "bearerAuth": [ "account:read" ] } ], "responses": { "200": { "description": "Retrieve the authenticated workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string" } }, "required": [ "id", "name", "slug", "plan" ], "additionalProperties": false }, "credit_balance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "entitlements": { "type": "object", "properties": { "quality_tiers": { "type": "array", "items": { "type": "string" } }, "custom_guidelines": { "type": "boolean" }, "max_glossaries": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "max_terms_per_glossary": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "max_upload_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "quality_tiers", "custom_guidelines", "max_glossaries", "max_terms_per_glossary", "max_upload_bytes" ], "additionalProperties": false }, "credential": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "api_key", "oauth" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "account:read", "usage:read", "batches:read", "batches:write", "batches:create", "files:write", "glossaries:read", "glossaries:write", "webhooks:write" ] } }, "created_at": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "kind", "name", "prefix", "scopes", "created_at", "expires_at" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "batch_creation": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "supported_formats": { "type": "array", "items": { "type": "string" } } }, "required": [ "batch_creation", "webhooks", "supported_formats" ], "additionalProperties": false } }, "required": [ "workspace", "credit_balance", "entitlements", "credential", "capabilities" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/credits": { "get": { "operationId": "getCredits", "summary": "Retrieve the credit balance and every grant", "description": "The current balance plus each grant with its remaining amount and expiry. `next_refill_estimated_at` is derived from the latest monthly grant's expiry and is an estimate, not a guarantee: the refill runs on a cron pass after that moment.", "tags": [ "credits" ], "parameters": [], "security": [ { "bearerAuth": [ "account:read" ] } ], "responses": { "200": { "description": "Retrieve the credit balance and every grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "balance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plan": { "type": "string" }, "monthly_allowance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "next_refill_estimated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "grants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "granted_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "type", "amount", "used", "remaining", "granted_at", "expires_at" ], "additionalProperties": false } } }, "required": [ "balance", "plan", "monthly_allowance", "next_refill_estimated_at", "grants" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Retrieve credit usage over time", "description": "Credits, completed translations and words over a range, bucketed by day, week or month. With no parameters it returns the last 30 days. Granularity defaults to the range length: day up to 31 days, week up to 180, month beyond.", "tags": [ "usage" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "day", "week", "month" ] } } ], "security": [ { "bearerAuth": [ "usage:read" ] } ], "responses": { "200": { "description": "Retrieve credit usage over time", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "granularity": { "type": "string", "enum": [ "day", "week", "month" ] }, "totals": { "type": "object", "properties": { "credits_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "batches_completed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "words_translated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "credits_used", "batches_completed", "words_translated" ], "additionalProperties": false }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "credits_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "batches_completed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "words_translated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "date", "credits_used", "batches_completed", "words_translated" ], "additionalProperties": false } } }, "required": [ "from", "to", "granularity", "totals", "points" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/batches": { "get": { "operationId": "listBatches", "summary": "List translations", "description": "Most recent first, archived excluded by default. Pagination is cursor-based: pass the `next_cursor` from the previous response verbatim. Offsets are not supported because a translation created mid-pagination would silently shift them. `search` matches a translation's name or, when it has none, its uploaded file name — the same search the web app's batch list uses, so results never diverge between the two.", "tags": [ "batches" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "analyzing", "awaiting_review", "translating", "completed", "failed" ] } }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } }, { "name": "quality_tier", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "standard", "lite" ] } }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "security": [ { "bearerAuth": [ "batches:read" ] } ], "responses": { "200": { "description": "List translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "analyzing", "awaiting_review", "translating", "completed", "failed" ] }, "translation_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quality_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "word_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "credit_cost": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_sample": { "type": "boolean" }, "archived": { "type": "boolean" }, "progress": { "type": "object", "properties": { "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "phase", "percent", "updated_at" ], "additionalProperties": false }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "file_name", "status", "translation_mode", "quality_tier", "word_count", "credit_cost", "is_sample", "archived", "progress", "error", "created_at", "completed_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/batches/{batch_id}": { "get": { "operationId": "getBatch", "summary": "Retrieve one translation", "description": "Fields that do not apply yet are null rather than absent, so the shape is stable across the whole lifecycle. A translation belonging to another workspace returns the same 404 as one that does not exist.", "tags": [ "batches" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "batches:read" ] } ], "responses": { "200": { "description": "Retrieve one translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "analyzing", "awaiting_review", "translating", "completed", "failed" ] }, "translation_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quality_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "word_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "credit_cost": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_sample": { "type": "boolean" }, "archived": { "type": "boolean" }, "progress": { "type": "object", "properties": { "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "phase", "percent", "updated_at" ], "additionalProperties": false }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "file_name", "status", "translation_mode", "quality_tier", "word_count", "credit_cost", "is_sample", "archived", "progress", "error", "created_at", "completed_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "patch": { "operationId": "updateBatch", "summary": "Rename or archive a translation", "description": "Only `name` and `archived` can change — exactly what a person can already change in the web app. This exists so housekeeping can be scripted, for example archiving everything older than 90 days.", "tags": [ "batches" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "batches:write" ] } ], "responses": { "200": { "description": "Rename or archive a translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "queued", "analyzing", "awaiting_review", "translating", "completed", "failed" ] }, "translation_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quality_tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "word_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "credit_cost": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_sample": { "type": "boolean" }, "archived": { "type": "boolean" }, "progress": { "type": "object", "properties": { "phase": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "phase", "percent", "updated_at" ], "additionalProperties": false }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "file_name", "status", "translation_mode", "quality_tier", "word_count", "credit_cost", "is_sample", "archived", "progress", "error", "created_at", "completed_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "archived": { "type": "boolean" } }, "additionalProperties": false } } } } } }, "/v1/batches/{batch_id}/result": { "get": { "operationId": "getBatchResult", "summary": "Download a finished translation", "description": "By default returns a signed link valid for 30 minutes, so the download goes straight to storage. Pass `?format=file` (or send `Accept: text/csv`) to stream the CSV back directly instead. Available only once the translation is `completed`.", "tags": [ "batches" ], "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "link", "file" ] } } ], "security": [ { "bearerAuth": [ "batches:read" ] } ], "responses": { "200": { "description": "Download a finished translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "byte_size": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "download_url": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "file_name", "byte_size", "download_url", "expires_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/glossaries": { "get": { "operationId": "listGlossaries", "summary": "List glossaries", "description": "One glossary per language pair, ordered alphabetically by pair, with its term count and the plan's cap. Terms themselves are omitted by default and returned only when you fetch a single glossary — or pass `expand=terms` here to get full content across a page of glossaries in one call. Pagination is cursor-based: pass the `next_cursor` from the previous response verbatim. `expand=terms` clamps the page size to 10, since a glossary's terms are otherwise unbounded in size.", "tags": [ "glossaries" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "expand", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "glossaries:read" ] } ], "responses": { "200": { "description": "List glossaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "language_pair": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "term_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_terms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "terms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "language_pair", "source_language", "target_language", "term_count", "max_terms", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "post": { "operationId": "createGlossary", "summary": "Create a glossary", "description": "Creates the glossary for a language pair, optionally with its first terms. Returns 409 if one already exists for that pair — use PATCH to add terms to it instead.", "tags": [ "glossaries" ], "parameters": [], "security": [ { "bearerAuth": [ "glossaries:write" ] } ], "responses": { "201": { "description": "Create a glossary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "glossary": { "type": "object", "properties": { "language_pair": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "term_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_terms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "terms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "language_pair", "source_language", "target_language", "term_count", "max_terms", "created_at", "updated_at" ], "additionalProperties": false }, "added": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "removed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "glossary", "added", "updated", "removed" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source_language": { "type": "string", "minLength": 1 }, "target_language": { "type": "string", "minLength": 1 }, "terms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "source_language", "target_language" ], "additionalProperties": false } } } } } }, "/v1/glossaries/{language_pair}": { "get": { "operationId": "getGlossary", "summary": "Retrieve a glossary with its terms", "description": "The language pair is the identifier — two supported tags joined by a hyphen, such as `en-US-fr`. Call GET /v1/languages for the catalogue.", "tags": [ "glossaries" ], "parameters": [ { "name": "language_pair", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "glossaries:read" ] } ], "responses": { "200": { "description": "Retrieve a glossary with its terms", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "language_pair": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "term_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_terms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "terms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "language_pair", "source_language", "target_language", "term_count", "max_terms", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "put": { "operationId": "replaceGlossaryTerms", "summary": "Replace every term in a glossary", "description": "Destructive: any term not present in the request is deleted. To add or remove a few terms without touching the rest, use PATCH.", "tags": [ "glossaries" ], "parameters": [ { "name": "language_pair", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "glossaries:write" ] } ], "responses": { "200": { "description": "Replace every term in a glossary", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "glossary": { "type": "object", "properties": { "language_pair": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "term_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_terms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "terms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "language_pair", "source_language", "target_language", "term_count", "max_terms", "created_at", "updated_at" ], "additionalProperties": false }, "added": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "removed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "glossary", "added", "updated", "removed" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "terms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "terms" ], "additionalProperties": false } } } } }, "patch": { "operationId": "patchGlossaryTerms", "summary": "Add, update or remove specific terms", "description": "Applied atomically: if the result would exceed the plan's cap the whole request is rejected rather than half-applied. Terms not mentioned are left untouched.", "tags": [ "glossaries" ], "parameters": [ { "name": "language_pair", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "glossaries:write" ] } ], "responses": { "200": { "description": "Add, update or remove specific terms", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "glossary": { "type": "object", "properties": { "language_pair": { "type": "string" }, "source_language": { "type": "string" }, "target_language": { "type": "string" }, "term_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_terms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "terms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "language_pair", "source_language", "target_language", "term_count", "max_terms", "created_at", "updated_at" ], "additionalProperties": false }, "added": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "removed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "glossary", "added", "updated", "removed" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "upsert": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "remove": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } } } }, "delete": { "operationId": "deleteGlossary", "summary": "Delete a glossary", "description": "Removes the glossary and all of its terms. This cannot be undone.", "tags": [ "glossaries" ], "parameters": [ { "name": "language_pair", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "glossaries:write" ] } ], "responses": { "204": { "description": "Delete a glossary" }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/languages": { "get": { "operationId": "listLanguages", "summary": "List supported languages", "description": "The canonical BCP 47 catalogue. Validate a language against this before attempting a glossary write, rather than learning from a 422. Identical for every workspace, and cacheable for an hour.", "tags": [ "languages" ], "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List supported languages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tag": { "type": "string" }, "label": { "type": "string" } }, "required": [ "tag", "label" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer" }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } } } }