Skip to content

Approvals Endpoints

List versions waiting for approval, compare them with the live version, and approve, revert or dismiss.

These endpoints work with Version Approval. Reading needs the read or manage scope. Approving, reverting and dismissing need the manage scope, and the teammate who created the token must be allowed to approve screenshots.

List waiting versions

GET /api/v1/approvals
GET /api/v1/approvals
Authorization: Bearer your-api-token
Response
{
  "count": 1,
  "versions": [
    {
      "screenshot_name": "Pricing page",
      "screenshot_id": 42,
      "variant_key": "default",
      "version": { "id": 312, "version_number": 8, "captured_at": "2026-10-05T09:12:44+00:00", "width": 1440, "height": 900, "image_url": "https://screenshotagent.com/..." },
      "live": { "id": 305, "version_number": 7, "captured_at": "2026-10-01T09:10:02+00:00", "width": 1440, "height": 900, "image_url": "https://screenshotagent.com/..." },
      "is_live": false,
      "waiting": true,
      "reason": "New capture waiting for approval",
      "change_from_previous_percent": 6.4
    }
  ]
}

image_url links are signed and expire after an hour. reason explains a held version, for example a blur that could not be re-applied.

Compare a version with the live one

GET /api/v1/screenshots/{id}/versions/{version}/compare
GET /api/v1/screenshots/42/versions/312/compare
Authorization: Bearer your-api-token

Returns the same fields as one item of the list, for any version of the screenshot.

Approve or revert

POST /api/v1/screenshots/{id}/versions/{version}/approve
POST /api/v1/screenshots/42/versions/312/approve
Authorization: Bearer your-api-token

Makes the version live. Pass an older version to revert to it. When that switches an Automatic screenshot to Needs approval, the response has switched_to_approval: true.

Dismiss

POST /api/v1/screenshots/{id}/versions/{version}/dismiss
POST /api/v1/screenshots/42/versions/312/dismiss
Authorization: Bearer your-api-token

Stops asking about a waiting version. Your embeds keep showing the live version.