Skip to content

AI Annotations Endpoint

Mark up a screenshot with AI from your scripts, then poll for the annotated version.

Create an AI annotation

POST /api/v1/screenshots/{id}/ai-annotations
POST /api/v1/screenshots/42/ai-annotations
Authorization: Bearer your-api-token
Content-Type: application/json

{
  "presets": ["hand_drawn_circle"],
  "instructions": "the Approve button"
}

Requires a token with the captures scope. Pass at least one preset or some instructions. It annotates the screenshot’s latest capture unless you pass a version_id.

FieldTypeDescription
presetsarrayAny of hand_drawn_circle, highlight_element, add_arrow, add_callout, blur_sensitive, add_browser_frame
instructionsstringThe element to mark (up to 2,000 characters). Instructions alone get a hand-drawn circle
version_idintegerAnnotate this version of the screenshot instead of the latest capture
Response (202 Accepted)
{
  "annotation": {
    "uuid": "9b1c0c5e-0f3a-4d8e-9a57-3c1f0e2b7d41",
    "screenshot_id": 42,
    "source_version_id": 311,
    "output_version_id": null,
    "source": "api",
    "method": "locate",
    "model": "gemini-3.1-flash-lite",
    "presets": ["hand_drawn_circle"],
    "prompt": "the Approve button",
    "status": "pending",
    "done": false,
    "error": null
  },
  "usage": { "used": 12, "limit": 2000, "remaining": 1987, "in_flight": 1 }
}

Check its status

GET /api/v1/ai-annotations/{uuid}
GET /api/v1/ai-annotations/9b1c0c5e-0f3a-4d8e-9a57-3c1f0e2b7d41
Authorization: Bearer your-api-token

Works with a read or captures token. status is pending or processing while it runs, then completed (with output_version_id set to the annotated version) or failed (with error). Poll every 5 to 10 seconds.

Errors

StatusMeaning
402The team has used its AI annotation allowance, or its trial ended. The body has a message and an upgrade_url.
403The token is missing the captures scope.
404No screenshot with that id in your team.
422No preset or instructions, an unknown preset, or a version that does not belong to the screenshot.

Each completed annotation uses one AI annotation from your plan; a browser frame alone is free. When the element can’t be found, the annotation fails with status failed and is not counted. See AI Annotations for presets, rules and allowances.