Get Capture Focus

POST /v2/agents/checks/capture-focus/get

Get Capture Focus

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/checks/capture-focus/get \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "organizationId": "<string>",
    "documentId": "<string>",
    "annotationId": "<string>"
  }
}
'

{
  "result": {
    "status": "success",
    "message": "Capture focus retrieved",
    "data": {
      "versionId": "ver_20261026a",
      "urlHash": "c82f1b5e",
      "device": "mobile",
      "rect": null,
      "pages": ["https://www.example.com/pricing"],
      "comment": {
        "annotationId": "P2nW8tY4kQ6mZcV3hJxL",
        "ruleKey": "image-broken",
        "scope": "page",
        "statusKind": "open"
      }
    }
  }
}

Use this API to find where a check’s comment sits on its captured screenshot. It returns the site version, the page, the device, the element’s box, the pages to walk through, and the comment’s row with its thumbnail. Use it to open a screenshot zoomed on the problem.

The comment must carry a check: an agent comment the engine keyed, or a person’s comment attached to a check. See Checks Overview.

​

Endpoint

POST https://api.velt.dev/v2/agents/checks/capture-focus/get

​

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

​

Body

​

Params

data · object · required

Show properties

organizationId · string · required

1 to 512 characters. The organization of the project.

documentId · string · required

1 to 512 characters. The document of the project.

annotationId · string · required

The comment annotation id. 1 to 512 characters, no /, and not . or ...

The schema uses .strict(): unknown fields are rejected.

​

Example Requests

{
  "data": {
    "organizationId": "org_acme",
    "documentId": "acme-marketing-site",
    "annotationId": "K7mQ2xR9vB4wLdT1sYpN"
  }
}

​

Response

​

Success Response

{
  "result": {
    "status": "success",
    "message": "Capture focus retrieved",
    "data": {
      "versionId": null,
      "urlHash": "a41c9e07",
      "device": "desktop",
      "rect": {
        "x": 812,
        "y": 4120,
        "width": 96,
        "height": 20,
        "viewportWidth": 1440
      },
      "pages": [
        "https://www.example.com/",
        "https://www.example.com/pricing",
        "https://www.example.com/about"
      ],
      "comment": {
        "annotationId": "K7mQ2xR9vB4wLdT1sYpN",
        "ruleKey": "link-broken",
        "pageUrl": "https://www.example.com/",
        "pagePath": "/",
        "scope": "site",
        "pageCount": 14,
        "locationType": "element",
        "evidenceLabel": "footer a[href=\"/careers\"]",
        "statusKind": "open",
        "pendingVerify": false,
        "thumbnailUrl": "https://storage.example.com/thumbs/a41c9e07.png",
        "isAgent": true
      }
    }
  }
}

The comment above is shortened. It has every field of a List Check Comments row.

Field	Type	Description
data.versionId	string | null	The site version of a page comment. null for a site comment, or when unknown.
data.urlHash	string | null	Hash of the comment’s page.
data.device	string	"desktop" or "mobile".
data.rect	object | null	The element’s box on the full-page capture, in CSS pixels: x, y, width, height and the capture’s viewportWidth. null when no box was measured, for example for a source or none comment.
data.pages	string[]	The comment’s pages. One entry for a page comment.
data.comment	object	The comment’s row, with its thumbnail.

​

Failure Response

{
  "error": {
    "message": "This comment was not written by a check",
    "status": "FAILED_PRECONDITION",
    "details": {
      "reason": "CHECKS_NOT_A_CHECK_COMMENT"
    }
  }
}

Errors: INVALID_ARGUMENT (a body outside the schema: a missing or malformed annotationId, or an unknown field) / NOT_FOUND with CHECKS_COMMENT_NOT_FOUND (no such comment in the project) or CHECKS_WORKSPACE_NOT_FOUND (the workspace has no store database) / FAILED_PRECONDITION with CHECKS_NOT_A_CHECK_COMMENT (the comment carries no check).

{
  "result": {
    "status": "success",
    "message": "Capture focus retrieved",
    "data": {
      "versionId": "ver_20261026a",
      "urlHash": "c82f1b5e",
      "device": "mobile",
      "rect": null,
      "pages": ["https://www.example.com/pricing"],
      "comment": {
        "annotationId": "P2nW8tY4kQ6mZcV3hJxL",
        "ruleKey": "image-broken",
        "scope": "page",
        "statusKind": "open"
      }
    }
  }
}