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.
| Field | Type | Description |
|---|---|---|
| presets | array | Any of hand_drawn_circle, highlight_element, add_arrow, add_callout, blur_sensitive, add_browser_frame |
| instructions | string | The element to mark (up to 2,000 characters). Instructions alone get a hand-drawn circle |
| version_id | integer | Annotate 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-tokenWorks 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
| Status | Meaning |
|---|---|
| 402 | The team has used its AI annotation allowance, or its trial ended. The body has a message and an upgrade_url. |
| 403 | The token is missing the captures scope. |
| 404 | No screenshot with that id in your team. |
| 422 | No 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.