About screenshots 🔗

To enable the Context Screenshots feature, you must activate the Professional or higher tier.

Localazy reserves some metadata keys for screenshots to function correctly - do not use the following keys in metadata:

  • name is used for a file name displayed in the web UI
  • ignoreSuggestedPhrases is used for maintaining the list of ignored suggested keys

List screenshots 🔗

[GET] /projects/{projectId}/screenshots
Type Value
Roles translator
Need write permission false
Produces application/json

Lists all screenshots in the project.

Params

Sample Request 🔗

curl --request GET \
  --url https://api.localazy.com/projects/{projectId}/screenshots \
  --header 'Authorization: Bearer {{token}}'

Sample Response 🔗

[{
  "id": "_a54984654651321345",
  "url": "https://cdn.localazy.com/screenshots/....",
  "comment": "Custom comment for the screenshots",
  "phrases": ["_a54984654651321345", "_a54984654651321345"],
  "tags": ["ui", "settings"],
  "ocrData": "Register new user",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}]

Response Object

Field Description
id Localazy identifier of a screenshot.
url The URL the screenshot is publicly available at.
comment Custom screenshot description.
phrases Identifiers of keys assigned to a screenshot.
tags A list of tags the screenshot is tagged with.
ocrData Data from the OCR reader. Only returned if the project belongs to an organization having the Autopilot or higher tier active.
metadata A key-value structure containing custom screenshot metadata.

List screenshots tags 🔗

[GET] /projects/{projectId}/screenshots/tags
Type Value
Roles translator
Need write permission false
Produces application/json

Lists an array of all tags for the given project. You can use project’s id or slug as {projectId}.

Sample Request 🔗

curl --request GET \
  --url https://api.localazy.com/projects/{projectId}/screenshots/tags \
  --header 'Authorization: Bearer {{token}}'

Sample Response 🔗

[
  "ui",
  "settings",
  "user_profile"
]

Create a new screenshot 🔗

[POST] /projects/{projectId}/screenshots
Type Value
Roles reviewer
Need write permission true
Produces application/json

Upload a new screenshot for the given project. You can use project’s id or slug as {projectId}.

Sample Request 🔗

curl --request POST \
  --url https://api.localazy.com/projects/{projectId}/screenshots \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data-raw 'data:image/png;base64,...'

Request Object

  • Image in data format with base64 encoding: data:image/jpeg;base64,… as RAW post data.

Limitations:

  • JPEG or PNG images are supported
  • The image must be larger or equal to 36x36
  • The image must be smaller or equal to 4096x4096
  • The image must be smaller than 5 MB

Sample Response 🔗

{
  "id": "_a5498465465132777"
}

Response Object

Field Description
id Identifier of the newly created screenshot.

Update existing screenshot 🔗

[POST] /projects/{projectId}/screenshots/{screenshotId}
Type Value
Roles reviewer
Need write permission true
Produces application/json

Change image data of an existing screenshot for the given project. You can use project’s id or slug as {projectId}.

POST method is used to distinguish between uploading new image data (POST) and changing screenshot metadata (PUT).

Sample Request 🔗

curl --request POST \
  --url https://api.localazy.com/projects/{projectId}/screenshots/{screenshotId} \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data-raw 'data:image/png;base64,...'

Request Object

  • Image in data format with base64 encoding: data:image/jpeg;base64,… as RAW post data.

Limitations:

  • JPEG or PNG images are supported
  • An image must be larger or equal to 36x36
  • An image must be smaller or equal to 4096x4096
  • An image must be smaller than 5 MB

Sample Response 🔗

{
  "result": true
}
Field Description
result Success status of operation

Update existing screenshot metadata 🔗

[PUT] /projects/{projectId}/screenshots/{screenshotId}
Type Value
Roles reviewer
Need write permission true
Produces application/json

Change data of an existing screenshot for the given project. You can use project’s id or slug as {projectId}.

Sample Request 🔗

curl --request PUT \
  --url https://api.localazy.com/projects/{projectId}/screenshots/{screenshotId} \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "comment": "Custom comment for the screenshots",
    "addTags": ["ui"],
    "removeTags": ["settings"],
    "tags": ["ui", "settings"],
    "addPhrases": ["_a54984654651321345"],
    "removePhrases": ["_a54984654651321567"],
    "phrases": ["_a54984654651321345", "_a54984654651321336"],
    "addMetadata": {
        "key3": "value3"
    },
    "removeMetadata": ["key1"],
    "metadata": {
        "key1": "value1",
        "key2": "value2"
    }
}'

Request Object

Field Description
comment Custom comment for a screenshot
addTags Add tags. Adding has priority over removing. It cannot be used together with tags.
removeTags Remove tags. Adding has priority over removing. It cannot be used together with tags.
tags Replace tags with the current value. Cannot be used together with addTags or/and removeTags.
addPhrases Adds keys. Adding has priority over removing. It cannot be used together with phrases.
removePhrases Removes keys. Adding has priority over removing. Cannot be used together with phrases.
phrases Replace phrases with the current value. Cannot be used together with addPhrases or/and removePhrases.
addMetadata Add metadata. Adding has priority over removing. It cannot be used together with metadata.
removeMetadata Remove metadata. Adding has priority over removing. It cannot be used together with metadata.
metadata Replace metadata with the current value. Cannot be used together with addMetadata or/and removeMetadata.

Notes:

  • All fields are optional; if omitted, the corresponding property is not changed.
  • Comment length is limited to 500 characters. If longer, only the first 500 characters are stored.
  • Tag length is limited to 64 characters. If longer, it’s filtered out and not stored.
  • Metadata key length is limited to 64 characters. If longer, it’s filtered out and not stored.
  • Metadata value length is limited to 8k characters. If longer, it’s filtered out and not stored.
  • Operated phrases must be from the same project.

Sample Response 🔗

{
  "result": true
}
Field Description
result Success status of operation

Delete a screenshot 🔗

[DELETE] /projects/{projectId}/screenshots/{screenshotId}
Type Value
Roles reviewer
Need write permission true
Produces application/json

Delete a screenshot for the given project. You can use project’s id or slug as {projectId}.

Sample Request 🔗

curl --request DELETE \
  --url https://api.localazy.com/projects/{projectId}/screenshots/{screenshotId} \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json'

Sample Response 🔗

{
  "result": true
}
Field Description
result Success status of operation