Create a capture

Runs the page in a headless browser, measures the elements you name, and returns what actually rendered. Geometry comes from getBoundingClientRect - nothing on this endpoint is estimated from a screenshot.

POST/v1/captures

Parameters

Request body, application/json
Name	Type	Required	Notes
url	string	yes	A path on a dev server this CLI started. Never a full URL - that field does not exist.
viewport	"desktop" \| "tablet" \| "mobile"	yes	Named, so a caller cannot invent geometry.
selectors	string[]	no	Elements to measure. Each returns x, y, width, height and computed styles.
settleMs	integer	no	Milliseconds to wait after load. Frameworks paint after the load event.
audit	boolean	no	Run the whole-DOM accessibility and layout audit.

Request

POST /v1/captures
Content-Type: application/json

{
  "url": "/dashboard",
  "viewport": "desktop",
  "selectors": ["aside", "header", "main"],
  "audit": true
}

Response 200

{
  "ok": true,
  "viewport": "desktop",
  "documentHeight": 1086,
  "measurements": [
    { "selector": "aside",  "found": true, "x": 0,   "y": 0, "width": 248,  "height": 1086 },
    { "selector": "header", "found": true, "x": 248, "y": 0, "width": 1192, "height": 99 },
    { "selector": "main",   "found": true, "x": 248, "y": 99, "width": 1192, "height": 986 }
  ],
  "audit": { "findings": [], "horizontalOverflow": false }
}

Responses

200Capture returned
409Dev server not running
422Selector matched nothing - found: false, never a zeroed box
503Browser could not start inside its memory cgroup

Limits

Concurrency

One browser at a time, inside a 700M memory cgroup. A second request queues rather than competing for the same RAM.

Capture timeout

45s

A page that has not fired load by then is captured anyway, with a warning attached rather than an error - a slow page is still a page.

Fictional API for a fictional platform. The shapes above are the ones this project actually uses, which is why the notes column is opinionated.