Context images are screenshots or visual references that help translators understand where and how text appears in the application UI. All endpoints are served under /v1/{workspaceUrl}/projects/{projectUrl}/contextImages and return application/json responses.

Authentication is required. Read operations require contextImagesView permission; write/delete operations require contextImagesManage permission.

Connection Types

When creating a context image, you choose how it connects to text segments:

Type	Description
`KEY_BASED`	Explicitly connect to segments by their file path and key
`TEXT_BASED`	Connect to segments by matching the exact text content
`IMAGE_BASED`	Automatically detect and connect text using OCR (optical character recognition)

Endpoints

`GET /v1/{workspaceUrl}/projects/{projectUrl}/contextImages` -- List context images

Returns a paginated list of context images for the specified project.

Query Parameters

Parameter	Type	Required	Description
`search`	string	No	Filter criteria. Use `"segments_not_present"` to find images not connected to any segments
`page`	int	No	Page number (standard Spring pagination)
`size`	int	No	Page size (standard Spring pagination)

Detail	Value
Auth	`contextImagesView` permission on the project
Response	`200` — paginated `PageResponse<V1ContextImageResponse>`

`POST /v1/{workspaceUrl}/projects/{projectUrl}/contextImages` -- Create a context image

Uploads a new context image and optionally connects it to text segments. Accepts multipart/form-data with two parts:

Form Parts

Part	Type	Required	Description
`file`	binary	Yes	The image file. Supported formats: PNG, JPG, JPEG, WEBP
`request`	JSON (`V1CreateContextImageRequest`)	Yes	Connection configuration and segment mappings

Request JSON — `V1CreateContextImageRequest`

Field	Type	Required	Description
`connectType`	string	Yes	`"KEY_BASED"`, `"TEXT_BASED"`, or `"IMAGE_BASED"`
`languageCode`	string	Yes	ISO 639-1 code (e.g. `"en"`, `"de"`) of the text on the image
`autoConnectSuggestions`	boolean	Yes	Auto-accept OCR suggestions. Only meaningful for `IMAGE_BASED`.
`description`	string	Yes	Description of what the image shows (nullable)
`segments`	array	Yes	Segment connections with highlight boxes (nullable, required for `KEY_BASED`/`TEXT_BASED`)

Segment Object — `V1ConnectSegment`

Field	Type	Description
`filePathAndKey`	object \| null	`{ "filePath": "...", "key": "..." }` — required for `KEY_BASED`
`text`	string \| null	Exact text content — required for `TEXT_BASED`
`highlightBox`	object \| null	`{ "left", "top", "width", "height" }` — pixel coordinates on the image

Example — KEY_BASED

{
  "connectType": "KEY_BASED",
  "autoConnectSuggestions": true,
  "description": "Screenshot of the edit screen",
  "languageCode": "en",
  "segments": [
    {
      "filePathAndKey": { "filePath": "strings.xml", "key": "action_edit" },
      "text": "Edit",
      "highlightBox": { "left": 500, "top": 500, "width": 100, "height": 100 }
    }
  ]
}

Example — IMAGE_BASED

{
  "connectType": "IMAGE_BASED",
  "autoConnectSuggestions": false,
  "description": "Screenshot with text to auto-connect",
  "languageCode": "de",
  "segments": null
}

Detail	Value
Auth	`contextImagesManage` permission on the project
Response	`201` — `V1ContextImageResponse` with image metadata

`DELETE /v1/{workspaceUrl}/projects/{projectUrl}/contextImages/{id}` -- Delete a context image

Permanently deletes the specified context image and all its segment connections. This action cannot be undone.

Path Parameters

Parameter	Type	Description
`id`	string	Unique context image identifier (e.g. `"ci_18USq6822XIv-19847171"`)

Detail	Value
Auth	`contextImagesManage` permission on the project
Response	`200` — empty body

Response Object — `V1ContextImageResponse`

Field	Type	Description
`id`	string	Unique identifier
`fileName`	string	Original uploaded file name
`description`	string	User-provided description
`imageUrl`	string	Cloudflare-hosted URL of the image
`projectTitle`	string	Title of the owning project
`languageCode`	string	Associated locale
`connectedSegmentTextsCount`	long	Number of connected segment texts
`segmentTextSuggestionsCount`	long	Number of suggested (unconfirmed) segment connections
`uploadSource`	string	How the image was uploaded (e.g. `"API"`)
`uploadStatus`	string	Upload processing status
`textDetectionStatus`	string	OCR text detection status
`createdAt`	timestamp	Creation timestamp
`updatedAt`	timestamp	Last update timestamp

Common Error Responses

Status	Meaning
`400`	Bad Request — invalid parameters, filter criteria, or file format
`401`	Unauthorized — authentication credentials are missing or invalid
`403`	Forbidden — insufficient permissions for the requested operation
`404`	Not Found — workspace, project, or context image does not exist