Skip to content

API V1 · Context Images

Create context image

POST
/v1/{workspaceUrl}/projects/{projectUrl}/contextImages
curl --request POST \
--url https://api.lingohub.com/v1/acme-corp/projects/my-project/contextImages \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: multipart/form-data' \
--form file=@translations.json

Creates and optionally connects context images to text segments.

workspaceUrl
required
string

The URL slug of the workspace. The project links that GET /v1/projects returns contain it: /v1/{workspaceUrl}/projects/{projectUrl}.

Example

acme-corp
projectUrl
required
string

The URL slug of the project within its workspace. The project links that GET /v1/projects returns contain it: /v1/{workspaceUrl}/projects/{projectUrl}.

Example

my-project
Media typemultipart/form-data
object
request
required

Defines how to create and connect the context image

object
connectType
required

Determines how the context image will be connected to text segments:

  • KEY_BASED: Explicitly connect to segments identified by their file path and key
  • TEXT_BASED: Connect to segments by matching the exact text content
  • IMAGE_BASED: Use OCR text detection to automatically find and connect matching text on the image
string
Allowed values: KEY_BASED TEXT_BASED IMAGE_BASED
description

Optional description providing context about what the image shows

string | null

Example

Screenshot of the settings page showing the language dropdown
languageCode
required

The ISO 639-1 language code (with optional regional variant) of the text segments this image relates to

string

Example

de
autoConnectSuggestions
required

When true, automatically accepts and connects OCR-detected text suggestions. Only applicable when connectType is IMAGE_BASED. When false, suggestions are created but require manual review.

boolean
segments

List of text segments to connect with their corresponding highlight box positions on the image. Required with at least one entry for KEY_BASED and TEXT_BASED connection types. Can be omitted or null for IMAGE_BASED when auto-connecting via OCR.

Array<object> | null

Represents a single text segment connection to a context image with its location on the image

object
filePathAndKey
required

The file path and key identifying the source text segment. Required for KEY_BASED connections. For TEXT_BASED connections, use the ‘text’ field instead.

One of:

Identifies a text segment by its source file location and unique key

object
filePath
required

The relative file path from the project root to the resource file containing the text. Example: ‘res/values/strings.xml’ or ‘i18n/en.json’

string
>= 1 characters

Example

resources/translations.json
key
required

The unique key identifier for the text within the resource file

string
>= 1 characters

Example

home.welcome_message
text
required

The actual text content of the segment to match. Used for TEXT_BASED connections or as a reference for KEY_BASED connections. This text helps translators understand the context of the segment.

string | null

Example

Hello, welcome to our application!
highlightBox
required

The rectangular region on the image that highlights where the text appears. Used to visually indicate which part of the image the text relates to. Coordinates are in pixels, with (0,0) being the top-left corner of the image.

One of:

Defines a rectangular highlight box on the context image. Used to visually indicate where specific text appears on the image. All coordinates are in pixels relative to the top-left corner (0,0) of the image.

object
left
required

The horizontal pixel coordinate of the left edge of the highlight box

number

Example

150
top
required

The vertical pixel coordinate of the top edge of the highlight box

number

Example

200
width
required

The width in pixels of the highlight box

number

Example

120
height
required

The height in pixels of the highlight box

number

Example

40
file
required
string format: binary

OK: Returns the created context image.

Media typeapplication/json

Response object containing details of a context image including its connection status and metadata

object
id
required

The unique identifier of the context image in the format ‘ci_<encrypted_id>’

string
name
required

The original filename of the uploaded context image

string
description
required

Optional user-provided description of the context image

string | null
imageUrl
required

The full URL to view the context image via Cloudflare Images CDN

string
projectTitle
required

The title of the project this context image belongs to

string
languageCode
required

The ISO 639-1 language code (with optional regional variant) this context image is associated with

string
connectedSegmentLanguagesCount
required

The count of text segments that are definitively connected to this context image

integer format: int64
segmentLanguagesSuggestionsCount
required

The count of text segment connection suggestions pending review

integer format: int64
source
required

The source channel through which the context image was uploaded

string
Allowed values: WEB API FIGMA SDK
uploadStatus
required

The current upload processing status of the image

string
Allowed values: PROCESSING DONE ERROR
textDetectionStatus
required

The current status of the OCR text detection process

string
Allowed values: SCHEDULED PROCESSING DONE ERROR
createdAt
required

The timestamp when the context image was originally uploaded

string format: date-time
updatedAt
required

The timestamp when the context image was last updated

string format: date-time

Example

{
"id": "ci_18USq6822XIv-19847171",
"description": "Screenshot of the main dashboard showing the navigation menu",
"languageCode": "en",
"source": "WEB",
"uploadStatus": "PROCESSING",
"textDetectionStatus": "SCHEDULED"
}

Bad Request: The request or file part is missing or the request is not valid JSON.

Media typeapplication/json
object
url
string
message
string
text
string

Example generated

{
"url": "example",
"message": "example",
"text": "example"
}

Unauthorized: Authentication credentials are missing or invalid.

Media typeapplication/json
object
error
object
code
string
description
string
status
string
Allowed values: 100 CONTINUE 101 SWITCHING_PROTOCOLS 102 PROCESSING 103 EARLY_HINTS 200 OK 201 CREATED 202 ACCEPTED 203 NON_AUTHORITATIVE_INFORMATION 204 NO_CONTENT 205 RESET_CONTENT 206 PARTIAL_CONTENT 207 MULTI_STATUS 208 ALREADY_REPORTED 226 IM_USED 300 MULTIPLE_CHOICES 301 MOVED_PERMANENTLY 302 FOUND 303 SEE_OTHER 304 NOT_MODIFIED 307 TEMPORARY_REDIRECT 308 PERMANENT_REDIRECT 400 BAD_REQUEST 401 UNAUTHORIZED 402 PAYMENT_REQUIRED 403 FORBIDDEN 404 NOT_FOUND 405 METHOD_NOT_ALLOWED 406 NOT_ACCEPTABLE 407 PROXY_AUTHENTICATION_REQUIRED 408 REQUEST_TIMEOUT 409 CONFLICT 410 GONE 411 LENGTH_REQUIRED 412 PRECONDITION_FAILED 413 CONTENT_TOO_LARGE 413 PAYLOAD_TOO_LARGE 414 URI_TOO_LONG 415 UNSUPPORTED_MEDIA_TYPE 416 REQUESTED_RANGE_NOT_SATISFIABLE 417 EXPECTATION_FAILED 418 I_AM_A_TEAPOT 421 MISDIRECTED_REQUEST 422 UNPROCESSABLE_CONTENT 422 UNPROCESSABLE_ENTITY 423 LOCKED 424 FAILED_DEPENDENCY 425 TOO_EARLY 426 UPGRADE_REQUIRED 428 PRECONDITION_REQUIRED 429 TOO_MANY_REQUESTS 431 REQUEST_HEADER_FIELDS_TOO_LARGE 451 UNAVAILABLE_FOR_LEGAL_REASONS 500 INTERNAL_SERVER_ERROR 501 NOT_IMPLEMENTED 502 BAD_GATEWAY 503 SERVICE_UNAVAILABLE 504 GATEWAY_TIMEOUT 505 HTTP_VERSION_NOT_SUPPORTED 506 VARIANT_ALSO_NEGOTIATES 507 INSUFFICIENT_STORAGE 508 LOOP_DETECTED 509 BANDWIDTH_LIMIT_EXCEEDED 510 NOT_EXTENDED 511 NETWORK_AUTHENTICATION_REQUIRED
validationErrors
Array<object>
object
field
string
errors
Array<object>
object
code
string
description
string
parameters
object
key
additional properties

Example

{
"error": {
"status": "100 CONTINUE"
}
}

Forbidden: The authenticated user does not have context image management permission on this project.

Media typeapplication/json
object
url
string
message
string
text
string

Example generated

{
"url": "example",
"message": "example",
"text": "example"
}

Not Found: The specified workspace or project does not exist.

Media typeapplication/json
object
message
required
string | null
items
required
Array<string> | null

Example generated

{
"message": "example",
"items": [
"example"
]
}

Unprocessable Entity: The request is invalid, e.g. a KEY_BASED or TEXT_BASED request without segments.

Media typeapplication/json
object
error
object
code
string
description
string
status
string
Allowed values: 100 CONTINUE 101 SWITCHING_PROTOCOLS 102 PROCESSING 103 EARLY_HINTS 200 OK 201 CREATED 202 ACCEPTED 203 NON_AUTHORITATIVE_INFORMATION 204 NO_CONTENT 205 RESET_CONTENT 206 PARTIAL_CONTENT 207 MULTI_STATUS 208 ALREADY_REPORTED 226 IM_USED 300 MULTIPLE_CHOICES 301 MOVED_PERMANENTLY 302 FOUND 303 SEE_OTHER 304 NOT_MODIFIED 307 TEMPORARY_REDIRECT 308 PERMANENT_REDIRECT 400 BAD_REQUEST 401 UNAUTHORIZED 402 PAYMENT_REQUIRED 403 FORBIDDEN 404 NOT_FOUND 405 METHOD_NOT_ALLOWED 406 NOT_ACCEPTABLE 407 PROXY_AUTHENTICATION_REQUIRED 408 REQUEST_TIMEOUT 409 CONFLICT 410 GONE 411 LENGTH_REQUIRED 412 PRECONDITION_FAILED 413 CONTENT_TOO_LARGE 413 PAYLOAD_TOO_LARGE 414 URI_TOO_LONG 415 UNSUPPORTED_MEDIA_TYPE 416 REQUESTED_RANGE_NOT_SATISFIABLE 417 EXPECTATION_FAILED 418 I_AM_A_TEAPOT 421 MISDIRECTED_REQUEST 422 UNPROCESSABLE_CONTENT 422 UNPROCESSABLE_ENTITY 423 LOCKED 424 FAILED_DEPENDENCY 425 TOO_EARLY 426 UPGRADE_REQUIRED 428 PRECONDITION_REQUIRED 429 TOO_MANY_REQUESTS 431 REQUEST_HEADER_FIELDS_TOO_LARGE 451 UNAVAILABLE_FOR_LEGAL_REASONS 500 INTERNAL_SERVER_ERROR 501 NOT_IMPLEMENTED 502 BAD_GATEWAY 503 SERVICE_UNAVAILABLE 504 GATEWAY_TIMEOUT 505 HTTP_VERSION_NOT_SUPPORTED 506 VARIANT_ALSO_NEGOTIATES 507 INSUFFICIENT_STORAGE 508 LOOP_DETECTED 509 BANDWIDTH_LIMIT_EXCEEDED 510 NOT_EXTENDED 511 NETWORK_AUTHENTICATION_REQUIRED
validationErrors
Array<object>
object
field
string
errors
Array<object>
object
code
string
description
string
parameters
object
key
additional properties

Example

{
"error": {
"status": "100 CONTINUE"
}
}