Recapture Endpoint Documentation

Endpoint

POST /api/v1/recapture

POST /api/v1/recapture
Authorization: Bearer your-api-token
Content-Type: application/json

Request body

Pass at least one filter to choose which screenshots to recapture. Filters combine with OR: a screenshot that matches any of them is queued. Requires a token with the captures scope.

JSON Body

{
  "project": 42,
  "tags": ["production", "marketing"],
  "urls": ["/pricing", "/docs/*"]
}

Field	Type	Description
all	boolean	Recapture every screenshot in the team
project	integer	Recapture screenshots in this project (the project ID)
tags	string[]	Recapture screenshots with any of these tag names
urls	string[]	Recapture screenshots whose URL path matches any of these patterns, e.g. /pricing or /docs/* (* is a wildcard)

Warning

A request with no filters is rejected with 422 Unprocessable Content. To recapture everything, send {"all": true}.

422 Unprocessable Content

{
  "message": "At least one filter (all, project, tags, or urls) is required.",
  "errors": {
    "filter": ["At least one filter (all, project, tags, or urls) is required."]
  }
}

Response

200 OK

{
  "queued": 12,
  "captures_used": 18,
  "skipped": 3,
  "skipped_reasons": {
    "already_capturing": 1,
    "daily_cap_exceeded": 2
  },
  "queued_ids": [101, 102, 103]
}

Screenshots that are already capturing are skipped, and so are any beyond your daily API capture budget. skipped_reasons only lists reasons that apply. captures_used is the number of images the queued screenshots produce: each screen size and color scheme of a screenshot is one image and uses one capture.

Errors

Status	Meaning
401	Missing, invalid or expired token
403	The token does not have the captures scope
402	Your plan or trial has no captures left
422	No filter was given, or a filter is invalid
429	Rate limit or daily capture ceiling reached
503	Captures are temporarily paused

CI/CD integration example

Trigger a recapture after every deployment to keep your documentation screenshots in sync:

GitHub Actions

- name: Recapture screenshots
  run: |
    curl -X POST https://screenshotagent.com/api/v1/recapture \
      -H "Authorization: Bearer ${{ secrets.SCREENSHOT_API_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"tags": ["production"]}'

Tip

Use tags to control which screenshots are recaptured in each deployment. Tag production screenshots with “production” and staging screenshots with “staging”, then filter by tag in your CI/CD pipeline.