# Context Images

LingoHub API V1 · [all operations](https://developers.lingohub.com/reference/v1.md)

Endpoints for the operations that can be performed on the context images

A context image is a screenshot that shows translators where a text appears. Listing needs the `contextImagesView` permission on the project; creating and deleting need `contextImagesManage`.

## Connection types

When you create a context image, `connectType` decides how LingoHub connects it to texts:

| Type | Meaning |
| --- | --- |
| `KEY_BASED` | You name the texts by file path and key. |
| `TEXT_BASED` | You give the exact text; LingoHub connects the texts that match it. |
| `IMAGE_BASED` | LingoHub detects the text on the image (OCR) and connects the texts it finds. |

## List context images

The list is paginated: `page` is the zero-based page index, `size` the page size, and `sort` takes `property,(asc|desc)`. The response holds the images in `content`, next to `pageNumber`, `pageSize`, `totalPages` and `totalElements`.

Filter the list with `urlFilter`, a JSON filter that you send URL-encoded. This filter returns the images that aren't connected to any text:

```json
{"where":{"_and":[{"contextImage[segments]":{"_npresent":true}}]}}
```

## Create a context image

Send a `multipart/form-data` request with two parts: `file`, the image, and `request`, a JSON document with the content type `application/json`.

```shell
curl -X POST "https://api.lingohub.com/v1/$WORKSPACE_URL/projects/$PROJECT_URL/contextImages" \
  -H "Authorization: Bearer $LINGOHUB_API_KEY" \
  -F "file=@screenshot.png" \
  -F 'request={"connectType":"IMAGE_BASED","languageCode":"en","autoConnectSuggestions":false};type=application/json'
```

Rules for `request`:

- `connectType` and `languageCode` are required. `languageCode` is the language of the text on the image.
- `segments` must have at least one entry for `KEY_BASED` and `TEXT_BASED`. Every entry needs `filePathAndKey` for `KEY_BASED` and `text` for `TEXT_BASED`. For `IMAGE_BASED`, omit `segments`.
- `highlightBox` marks where the text appears on the image: `left`, `top`, `width` and `height` in pixels, measured from the top-left corner.
- `autoConnectSuggestions` matters only for `IMAGE_BASED`: `true` connects the detected texts at once, `false` stores them as suggestions for review.
- `description` is optional.

```json
{
  "connectType": "KEY_BASED",
  "autoConnectSuggestions": false,
  "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 }
    }
  ]
}
```

The response is `200` with the new context image. LingoHub connects the texts after the request, so both counts are `0` in this response; read the list later for the result.

## Response fields

| Field | Meaning |
| --- | --- |
| `id` | ID of the context image, for example `ci_18USq6822XIv-19847171`. Use it to delete the image. |
| `name` | File name of the uploaded image. |
| `imageUrl` | URL of the image. |
| `languageCode` | Language of the text on the image. |
| `connectedSegmentLanguagesCount` | Number of texts connected to the image. |
| `segmentLanguagesSuggestionsCount` | Number of suggested connections that wait for review. |
| `source` | Where the image came from: `WEB`, `API`, `FIGMA` or `SDK`. |
| `uploadStatus` | `PROCESSING`, `DONE` or `ERROR`. |
| `textDetectionStatus` | Status of the text detection: `SCHEDULED`, `PROCESSING`, `DONE` or `ERROR`. |

## Delete a context image

The operation deletes the image and its connections and answers `200` with an empty body.

## Errors

| Status | Meaning |
| --- | --- |
| `400` | The request is malformed, for example a missing part or an invalid ID. |
| `401` | The API key is missing or invalid. |
| `403` | The key lacks the permission the operation needs. |
| `404` | The workspace, the project or the context image doesn't exist. |
| `422` | `request` is invalid, for example `segments` is missing for `KEY_BASED`. |

## Operations

- [`GET /v1/{workspaceUrl}/projects/{projectUrl}/contextImages`](https://developers.lingohub.com/reference/v1/operations/v1contextimagesgetcontextimages.md): List context images
- [`POST /v1/{workspaceUrl}/projects/{projectUrl}/contextImages`](https://developers.lingohub.com/reference/v1/operations/v1contextimagescreatecontextimage.md): Create context image
- [`DELETE /v1/{workspaceUrl}/projects/{projectUrl}/contextImages/{id}`](https://developers.lingohub.com/reference/v1/operations/v1contextimagesdeletecontextimages.md): Delete context image
