# Upload a context image

`POST https://api.lingohub.com/v2/projects/{projectId}/context-images`

LingoHub API V2 (Beta) · [Context Images](https://developers.lingohub.com/reference/v2/operations/tags/context-images.md) · operation `createContextImage`

Uploads an image, at most 10 MB, that shows the UI text of one project language.

- Without `rendered_strings`, LingoHub reads the text in the image after the upload and links the segments it finds; with `auto_connect_suggestions: false` they stay suggestions to review in the app. Those links aren't in the response yet.
- With `rendered_strings`, as the iOS and Android SDKs send them, the image is linked right away to the segments whose keys or text match, and no text recognition runs. `[]` uploads the image without links.
- With `capture_key`, uploading the same screen again keeps the image's id: identical bytes change nothing (200 `UNCHANGED`); changed bytes replace the file and rebuild all its links, including ones added by hand (200 `REPLACED`). A new image answers 201 `CREATED`.

Every stored upload counts toward the workspace's monthly context image uploads. A segment keeps its three most recently linked images; linking a fourth detaches the oldest. Requires project-level context-image management permission.

## Parameters

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `projectId` | path | yes | string | Unique identifier of the project. |
| `Idempotency-Key` | header | no | string | Optional unique key for best-effort POST retry protection. The key is reserved, the request runs with ordinary service transactions, then the successful response is retained separately for 24 hours by default. There is n… |

## Example request

```sh
curl --request POST \
  --url https://api.lingohub.com/v2/projects/pr_0197c8f2-5a6b-7cde-8f12-3456789abcde/context-images \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@translations.json \
  --form language_code=en \
  --form name=checkout-screen.png \
  --form 'description=Screenshot of the checkout screen showing the payment options.' \
  --form auto_connect_suggestions=true \
  --form capture_key=checkout/payment-sheet \
  --form app_version=2.1.0
```

## Responses

- `200`: Capture replaced or unchanged.
- `201`: Context image uploaded successfully.
- `400`: 
- `401`: 
- `403`: 
- `404`: 
- `409`: The workspace has used up the monthly context image uploads of its plan (`context_image_limit_reached`). An unresolved request returns `idempotency_outcome_unknown` without Retry-After; inspect the affected resource befo…
- `413`: The upload exceeds the maximum size.
- `422`: A form field is invalid; `errors` names it. For `file`: `format` when it is not an image, `file_too_large` over 10 MB. `language_code` is not a language code (`format`) or not a language of the project (`not_found`). `na…
- `429`: 
- `500`: 
- `502`: The image service failed to store the image (`upstream_error`); retry later.
- `503`: 

## OpenAPI definition

The complete definition of this operation, with every schema it references:

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "LingoHub API V2 (Beta)",
    "version": "2.0"
  },
  "servers": [
    {
      "url": "https://api.lingohub.com",
      "description": "LingoHub"
    }
  ],
  "tags": [
    {
      "name": "Context Images",
      "description": "Upload screenshots that show translators and LINAs where a text appears. An image belongs to one project language and can be attached to segments of that project."
    }
  ],
  "paths": {
    "/v2/projects/{projectId}/context-images": {
      "post": {
        "tags": [
          "Context Images"
        ],
        "summary": "Upload a context image",
        "description": "Uploads an image, at most 10 MB, that shows the UI text of one project language.\n\n- Without `rendered_strings`, LingoHub reads the text in the image after the upload and links the segments it finds; with `auto_connect_suggestions: false` they stay suggestions to review in the app. Those links aren't in the response yet.\n- With `rendered_strings`, as the iOS and Android SDKs send them, the image is linked right away to the segments whose keys or text match, and no text recognition runs. `[]` uploads the image without links.\n- With `capture_key`, uploading the same screen again keeps the image's id: identical bytes change nothing (200 `UNCHANGED`); changed bytes replace the file and rebuild all its links, including ones added by hand (200 `REPLACED`). A new image answers 201 `CREATED`.\n\nEvery stored upload counts toward the workspace's monthly context image uploads. A segment keeps its three most recently linked images; linking a fourth detaches the oldest. Requires project-level context-image management permission.",
        "operationId": "createContextImage",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "description": "Unique identifier of the project.",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Public id that is created from the type prefix of the corresponding resource and its UUID. I.e : For a project, a valid value would be : pr_0197c8f2-5a6b-7cde-8f12-3456789abcde",
              "pattern": "^pr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
            },
            "example": "pr_0197c8f2-5a6b-7cde-8f12-3456789abcde"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Optional unique key for best-effort POST retry protection. The key is reserved, the request runs with ordinary service transactions, then the successful response is retained separately for 24 hours by default. There is no request-wide transaction or atomic commit between the operation and its replay result. A matching cached response is replayed verbatim with `Idempotent-Replayed: true`. Loss or expiry of the retained response can remove protection and allow re-execution. Uploads and chunked bodies are covered; multipart boundaries and JSON property order may differ. Retries still pass validation and current authorization; a later 403/404 does not undo the original operation. A changed payload returns 422 `idempotency_key_mismatch`. A recent active reservation returns 409 `idempotency_key_in_use` with `Retry-After`. A retry with an unresolved key, including an unfinished reservation older than 5 minutes, returns 409 `idempotency_outcome_unknown` without `Retry-After`. This timeout does not release the reservation or permit re-execution while it is retained. Inspect the affected resource before starting a new operation; do not blindly reuse an unresolved key after expiry. A 4xx rejection releases the reservation, allowing the same key to be retried after correcting the cause. A 5xx or interruption after execution starts leaves it unresolved. An unavailable reservation store returns 503 before execution; an oversized request returns 413. Cache-save failure or a response over the cache limit preserves the original success status, headers and body; only future retries become unresolved. When idempotency is explicitly disabled by server configuration, the header is ignored and requests execute normally without retry protection. Use a new unique key for each intended operation.",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255,
              "minLength": 1
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The image, at most 10 MB."
                  },
                  "language_code": {
                    "type": "string",
                    "description": "Language of the UI text shown in the image. The image can only be attached to segment texts of this language, and the language must be configured for the project.",
                    "example": "en"
                  },
                  "name": {
                    "type": "string",
                    "description": "Display name of the context image, at most 4096 characters. Omit it to use the uploaded file's name.",
                    "example": "checkout-screen.png",
                    "maxLength": 4096
                  },
                  "description": {
                    "type": "string",
                    "description": "What the image shows, at most 4096 characters.",
                    "example": "Screenshot of the checkout screen showing the payment options.",
                    "maxLength": 4096
                  },
                  "auto_connect_suggestions": {
                    "type": "boolean",
                    "default": true,
                    "description": "How the segments matched by OCR text-detection are connected: `true` (the default) connects them to the image, `false` creates suggestions that require manual review in the web editor.",
                    "example": true
                  },
                  "capture_key": {
                    "type": "string",
                    "description": "Stable capture identity within this project language. Same bytes are a no-op; changed bytes replace all links at the same image id.",
                    "example": "checkout/payment-sheet",
                    "maxLength": 512
                  },
                  "app_version": {
                    "type": "string",
                    "description": "Application version of this capture.",
                    "example": "2.1.0",
                    "maxLength": 256
                  },
                  "rendered_strings": {
                    "type": "array",
                    "description": "JSON array part with Content-Type application/json, at most 1000 strings. `[]` uploads the image without links; leave it out to let LingoHub read the text in the image.",
                    "items": {
                      "$ref": "#/components/schemas/ContextImageRenderedString"
                    },
                    "maxItems": 1000
                  }
                },
                "required": [
                  "file",
                  "language_code"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Capture replaced or unchanged.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "Location": {
                "description": "URL of the context image.",
                "style": "simple",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContextImageUpload"
                }
              }
            }
          },
          "201": {
            "description": "Context image uploaded successfully.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "Location": {
                "description": "URL of the created context image.",
                "style": "simple",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContextImageUpload"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The workspace has used up the monthly context image uploads of its plan (`context_image_limit_reached`). An unresolved request returns `idempotency_outcome_unknown` without Retry-After; inspect the affected resource before starting a new operation. A recent request with the same Idempotency-Key is still being processed (`idempotency_key_in_use`); retry after the number of seconds in the `Retry-After` header.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait for an in-progress keyed request; absent for other conflicts.",
                "schema": {
                  "type": "integer",
                  "format": "int32"
                }
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "The upload exceeds the maximum size.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "A form field is invalid; `errors` names it. For `file`: `format` when it is not an image, `file_too_large` over 10 MB. `language_code` is not a language code (`format`) or not a language of the project (`not_found`). `name` and `description` are longer than 4096 characters (`maxLength`); `auto_connect_suggestions` is neither true nor false (`type`). A `rendered_strings` box outside the image is `maximum` on its `width` or `height`.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "502": {
            "description": "The image service failed to store the image (`upstream_error`); retry later.",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ContextImageRenderedString": {
        "type": "object",
        "additionalProperties": false,
        "description": "One rendered string and its candidate keys. Exactly one matching segment gives a KEY_BASED link; ambiguity gives suggestions. With no key match, exact text matches give suggestions, or TEXT_BASED links when auto_connect_suggestions is true.",
        "properties": {
          "keys": {
            "type": "array",
            "description": "Candidate SDK keys; an empty list uses text matching.",
            "example": [
              {
                "key": "checkout.title",
                "table": "app.messages"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/ContextImageCaptureKey"
            },
            "maxItems": 10,
            "minItems": 0
          },
          "text": {
            "type": "string",
            "description": "The text as rendered on the screen.",
            "example": "Pay now",
            "maxLength": 50000,
            "minLength": 0
          },
          "highlight_box": {
            "description": "Where the string appears in the image. The boxes of all rendered strings that hit the same segment become its highlight boxes.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContextImageHighlightBox"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "keys",
          "text"
        ]
      },
      "ContextImageCaptureKey": {
        "type": "object",
        "additionalProperties": false,
        "description": "One key as looked up by the mobile SDK, optionally scoped to an iOS table.",
        "properties": {
          "key": {
            "type": "string",
            "description": "Absolute resource key, matched exactly.",
            "example": "checkout.title",
            "maxLength": 50000,
            "minLength": 0
          },
          "table": {
            "type": [
              "string",
              "null"
            ],
            "description": "iOS table name without file extension; null matches across the default branch.",
            "example": "app.messages",
            "maxLength": 16384,
            "minLength": 0
          }
        },
        "required": [
          "key"
        ]
      },
      "ContextImageHighlightBox": {
        "type": "object",
        "description": "A region of the image in whole pixels, measured from its top left corner. The box must lie inside the image.",
        "properties": {
          "left": {
            "type": "integer",
            "format": "int32",
            "description": "Distance of the box's left edge from the image's left edge.",
            "example": 40,
            "minimum": 0
          },
          "top": {
            "type": "integer",
            "format": "int32",
            "description": "Distance of the box's top edge from the image's top edge.",
            "example": 120,
            "minimum": 0
          },
          "width": {
            "type": "integer",
            "format": "int32",
            "description": "Width of the box.",
            "example": 200,
            "minimum": 1
          },
          "height": {
            "type": "integer",
            "format": "int32",
            "description": "Height of the box.",
            "example": 48,
            "minimum": 1
          }
        },
        "required": [
          "height",
          "left",
          "top",
          "width"
        ]
      },
      "ContextImageUpload": {
        "type": "object",
        "description": "A visual context image attached to segments of a project, giving translators and AI agents visual context for the text they work on.",
        "properties": {
          "object_type": {
            "type": "string",
            "description": "Always `CONTEXT_IMAGE`.",
            "enum": [
              "CONTEXT_IMAGE"
            ],
            "example": "CONTEXT_IMAGE"
          },
          "id": {
            "type": "string",
            "description": "Unique identifier of the context image.",
            "example": "ci_0197c8f2-5a6b-7cde-8f12-3456789abcde",
            "minLength": 1,
            "pattern": "^ci_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
          },
          "project_id": {
            "type": "string",
            "description": "Unique identifier of the project this context image belongs to.",
            "example": "pr_0197c8f2-5a6b-7cde-8f12-3456789abcde",
            "pattern": "^pr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
          },
          "name": {
            "type": "string",
            "description": "Display name of the context image (defaults to the uploaded file's name).",
            "example": "checkout-screen.png",
            "maxLength": 4096,
            "minLength": 0
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional description of what the image shows.",
            "example": "Screenshot of the checkout screen showing the payment options.",
            "maxLength": 4096,
            "minLength": 0
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "URL of the image at its original size, loadable as returned. Anyone holding the URL can view the image. Null while the upload is still processing or when it failed.",
            "example": "https://imagedelivery.net/abc/production/context_images/ci_0197c8f2-5a6b-7cde-8f12-3456789abcde/checkout-screen.png/con8192x8192"
          },
          "language_code": {
            "type": "string",
            "description": "Language of the UI text shown in the image. Attachments link to segment texts of this language.",
            "example": "en"
          },
          "width": {
            "type": "integer",
            "format": "int32",
            "description": "Width of the image in pixels.",
            "example": 1280
          },
          "height": {
            "type": "integer",
            "format": "int32",
            "description": "Height of the image in pixels.",
            "example": 720
          },
          "upload_status": {
            "$ref": "#/components/schemas/ContextImageUploadStatus",
            "description": "Processing state of the uploaded image file.",
            "example": "DONE"
          },
          "attachments": {
            "type": "array",
            "description": "The segments the image is attached to, with their highlight boxes. Links that text recognition finds after the upload aren't in it yet.",
            "example": [
              {
                "segment_id": "seg_0197c8f2-5a6b-7cde-8f12-3456789abcde",
                "highlight_boxes": [
                  {
                    "left": 40,
                    "top": 120,
                    "width": 200,
                    "height": 48
                  }
                ]
              }
            ],
            "items": {
              "$ref": "#/components/schemas/ContextImageAttachment"
            }
          },
          "capture_key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-chosen screen identity, scoped to this project language; null for ordinary uploads.",
            "example": "checkout/payment-sheet"
          },
          "content_hash": {
            "type": [
              "string",
              "null"
            ],
            "description": "SHA-256 hex of the stored image bytes; null for historical uploads.",
            "example": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
          },
          "app_version": {
            "type": [
              "string",
              "null"
            ],
            "description": "Client-reported application version of the last stored capture.",
            "example": "2.1.0"
          },
          "captured_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the current image file was stored. Metadata edits and unchanged captures do not move this timestamp; null for historical uploads.",
            "example": "2026-10-08T10:30:00.123Z"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the context image was created.",
            "example": "2025-01-15T10:30:00.123Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the context image was last updated.",
            "example": "2025-06-20T14:45:00.123Z"
          },
          "outcome": {
            "$ref": "#/components/schemas/ContextImageCaptureOutcome",
            "description": "What this upload did.",
            "example": "CREATED"
          }
        },
        "required": [
          "app_version",
          "attachments",
          "capture_key",
          "captured_at",
          "content_hash",
          "created_at",
          "description",
          "height",
          "id",
          "language_code",
          "name",
          "object_type",
          "outcome",
          "project_id",
          "updated_at",
          "upload_status",
          "url",
          "width"
        ]
      },
      "ContextImageUploadStatus": {
        "type": "string",
        "description": "Processing state of the uploaded image file:\n  - PROCESSING: the image file is still being stored\n  - DONE: the image file is stored and its `url` is available\n  - ERROR: storing the image file failed\n",
        "enum": [
          "PROCESSING",
          "DONE",
          "ERROR"
        ]
      },
      "ContextImageAttachment": {
        "type": "object",
        "description": "A segment the context image is attached to, at the segment's text in the image's language.",
        "properties": {
          "segment_id": {
            "type": "string",
            "description": "Unique identifier of the attached segment.",
            "example": "seg_0197c8f2-5a6b-7cde-8f12-3456789abcde",
            "pattern": "^seg_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
          },
          "highlight_boxes": {
            "type": "array",
            "description": "Where the segment's text appears in the image, in pixels. Empty when no place is marked.",
            "example": [
              {
                "left": 40,
                "top": 120,
                "width": 200,
                "height": 48
              }
            ],
            "items": {
              "$ref": "#/components/schemas/ContextImageHighlightBox"
            }
          }
        },
        "required": [
          "highlight_boxes",
          "segment_id"
        ]
      },
      "ContextImageCaptureOutcome": {
        "type": "string",
        "description": "CREATED stores a new image; REPLACED stores a new file at the same image identity; UNCHANGED leaves all stored data and upload usage unchanged.",
        "enum": [
          "CREATED",
          "REPLACED",
          "UNCHANGED"
        ]
      },
      "Error": {
        "type": "object",
        "description": "RFC 9457 problem details. `code` identifies the problem type (one per `type` URL); `errors` lists rejected fields or parameters; `required_permission` names the permission a 403 lacked.",
        "properties": {
          "type": {
            "type": "string",
            "description": "URL identifying the problem type and pointing to its documentation.",
            "example": "https://api.lingohub.com/errors/resource-not-found"
          },
          "title": {
            "type": "string",
            "description": "Short, constant summary of the problem type.",
            "example": "Resource not found"
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "HTTP status code.",
            "example": 404
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation of this occurrence of the problem.",
            "example": "Resource with ID 'pr_0197c8f2-5a6b-7cde-8f12-3456789abcde' was not found."
          },
          "instance": {
            "type": "string",
            "description": "Path of the request that produced the problem.",
            "example": "/v2/projects/pr_0197c8f2-5a6b-7cde-8f12-3456789abcde"
          },
          "code": {
            "$ref": "#/components/schemas/ErrorCode",
            "description": "Machine-readable problem type.",
            "example": "resource_not_found"
          },
          "request_id": {
            "type": "string",
            "description": "Correlation id of the request, also returned in the `X-Request-ID` header. Quote it when contacting support.",
            "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
          },
          "errors": {
            "type": "array",
            "description": "Rejected fields or parameters. Present when the problem concerns specific fields or parameters.",
            "example": [
              {
                "detail": "must be at least 2 characters long",
                "pointer": "#/name",
                "parameter": "limit",
                "code": "minLength"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/FieldError"
            }
          },
          "required_permission": {
            "$ref": "#/components/schemas/RequiredPermission",
            "description": "The permission the API key lacks. Present on 403 responses."
          }
        },
        "required": [
          "code",
          "detail",
          "instance",
          "request_id",
          "status",
          "title",
          "type"
        ]
      },
      "ErrorCode": {
        "type": "string",
        "description": "Machine-readable problem type of a V2 error response. Each code has a fixed HTTP status and documentation at its `type` URL.",
        "enum": [
          "invalid_json",
          "invalid_parameter",
          "missing_parameter",
          "unknown_parameter",
          "invalid_filter",
          "invalid_cursor",
          "bad_request",
          "missing_api_key",
          "invalid_api_key",
          "expired_api_key",
          "revoked_api_key",
          "disabled_api_key",
          "insufficient_permissions",
          "resource_not_found",
          "route_not_found",
          "method_not_allowed",
          "not_acceptable",
          "precondition_failed",
          "content_too_large",
          "unsupported_media_type",
          "already_exists",
          "idempotency_outcome_unknown",
          "idempotency_key_in_use",
          "stack_not_empty",
          "branch_not_ready",
          "backup_not_ready",
          "backup_in_use",
          "default_branch_protected",
          "owner_membership_protected",
          "source_language_protected",
          "branch_limit_reached",
          "context_image_limit_reached",
          "automation_limit_reached",
          "translation_order_pending",
          "git_integration_not_configured",
          "branch_git_integration_not_configured",
          "git_integration_unauthorized",
          "conflict",
          "validation_failed",
          "idempotency_key_mismatch",
          "rate_limit_exceeded",
          "internal_error",
          "upstream_error",
          "service_unavailable",
          "upstream_timeout"
        ]
      },
      "FieldError": {
        "type": "object",
        "description": "A rejected field or parameter. `pointer` locates a body field (RFC 6901 JSON Pointer), `parameter` a query, path or header parameter or a field of a multipart upload; both are set for a position inside a JSON-valued parameter such as `filter`.",
        "properties": {
          "detail": {
            "type": "string",
            "description": "Human-readable description of the problem.",
            "example": "must be at least 2 characters long"
          },
          "pointer": {
            "type": [
              "string",
              "null"
            ],
            "description": "JSON Pointer to the offending body field, or to the position inside a JSON-valued parameter.",
            "example": "#/name"
          },
          "parameter": {
            "type": [
              "string",
              "null"
            ],
            "description": "Name of the offending query, path or header parameter, or of the multipart form field.",
            "example": "limit"
          },
          "code": {
            "$ref": "#/components/schemas/FieldErrorCode",
            "description": "Why the field or parameter was rejected.",
            "example": "minLength"
          }
        },
        "required": [
          "code",
          "detail",
          "parameter",
          "pointer"
        ]
      },
      "FieldErrorCode": {
        "type": "string",
        "description": "Why a field or parameter was rejected: the JSON Schema keyword of the violated rule, or one of the documented rules that no schema can express.",
        "enum": [
          "required",
          "type",
          "enum",
          "minLength",
          "maxLength",
          "minimum",
          "maximum",
          "pattern",
          "format",
          "additionalProperties",
          "minItems",
          "maxItems",
          "uniqueItems",
          "already_exists",
          "not_found",
          "not_supported",
          "unsupported_file_extension",
          "file_too_large",
          "file_empty",
          "invalid_archive",
          "empty_archive"
        ]
      },
      "RequiredPermission": {
        "type": "object",
        "description": "The permission the API key lacks, in the vocabulary of the API key permission settings.",
        "properties": {
          "scope": {
            "$ref": "#/components/schemas/PermissionScope",
            "description": "Where the permission applies.",
            "example": "STACK"
          },
          "target": {
            "$ref": "#/components/schemas/PermissionTarget",
            "description": "The area the permission governs.",
            "example": "SETTINGS"
          },
          "level": {
            "$ref": "#/components/schemas/PermissionLevel",
            "description": "The access level required.",
            "example": "MANAGE"
          }
        },
        "required": [
          "level",
          "scope",
          "target"
        ]
      },
      "PermissionScope": {
        "type": "string",
        "description": "Where a permission applies: `WORKSPACE` permissions cover workspace-level resources, `STACK` permissions the resources of a stack (its projects, branches, resources, languages, ...).",
        "enum": [
          "WORKSPACE",
          "STACK"
        ]
      },
      "PermissionTarget": {
        "type": "string",
        "description": "The area a permission governs.",
        "enum": [
          "GENERAL",
          "BILLING_SUBSCRIPTION",
          "WORKSPACES",
          "MEMBERS",
          "PLUGINS_INTEGRATIONS",
          "LOGS",
          "API_ACCESS",
          "STACKS",
          "TRANSLATION_ORDERS",
          "WORK_REPORTS",
          "STYLE_GUIDES",
          "GLOSSARIES",
          "TRANSLATION_MEMORIES",
          "LABELS",
          "AI_TRANSLATION",
          "QUICK_TRANSLATIONS",
          "SETTINGS",
          "ACTIVITIES",
          "RESOURCES",
          "CONTEXT_IMAGES",
          "LANGUAGES",
          "SEGMENT_KEYS",
          "SEGMENTS",
          "SEGMENT_TEXTS"
        ]
      },
      "PermissionLevel": {
        "type": "string",
        "description": "Access level of a permission: `MANAGE` includes `WRITE` and `VIEW`.",
        "enum": [
          "NO_ACCESS",
          "VIEW",
          "WRITE",
          "MANAGE"
        ]
      }
    },
    "headers": {
      "RateLimit": {
        "description": "State of the rate-limit policy currently closest to rejection (IETF draft-ietf-httpapi-ratelimit-headers): the quoted policy name with `r` = requests remaining right now and `t` = seconds until the full quota is available again. Example: `\"api-key\";r=42;t=7`. Advisory: absent when the request fails authentication or the limiter state is momentarily unknown.",
        "schema": {
          "type": "string"
        }
      },
      "Idempotent-Replayed": {
        "description": "True when the original successful result was replayed for this key.",
        "schema": {
          "type": "boolean"
        }
      },
      "ETag": {
        "description": "Opaque strong validator for this representation. Keep its quotation marks and use it as If-Match on a documented conditional write. A replay carries the original ETag, which may now be stale.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimit-Policy": {
        "description": "The rate-limit policies applied to the request: each quoted policy name with `q` = sustained request quota per window of `w` seconds. Example: `\"api-key\";q=180;w=60, \"workspace\";q=600;w=60`. Advisory: absent when the request fails authentication or the limiter state is momentarily unknown.",
        "schema": {
          "type": "string"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "integer",
          "format": "int32"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is malformed: an unknown or invalid query parameter, an invalid id in the path, or a body that is not valid JSON. `code` names the problem, `errors` the parameter or field.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid or missing API key.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Insufficient permissions.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource does not exist, or the API key cannot see it.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "The API rate limit was exceeded. Wait for the number of seconds given in the Retry-After header, then retry.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "An unexpected internal server error occurred.",
        "headers": {
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The service is temporarily unavailable. Retry after the number of seconds in the Retry-After header.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "RateLimit": {
            "$ref": "#/components/headers/RateLimit"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "API key authentication. Create API keys in your LingoHub workspace settings. Keys use the `lh-api_` prefix. Pass the full key as the Bearer token.",
        "scheme": "bearer"
      }
    }
  }
}
````
