# Amazzing Screenshots

> URL in, pixels out. A screenshot API with no signup, no API keys, no ceremony.
> Built to give AI agents vision; doubles as a cost-effective screenshot service.

## The one-liner

    GET https://shot.amazz.ing?url=https://example.com

Returns the screenshot bytes (image/png by default). Add `output=url` to get a
JSON payload with a hosted image URL instead.

## Full API

### Capture

    POST https://amazz.ing/api/screenshots
    Content-Type: application/json

    {
      "url": "https://example.com",   // required, http/https only
      "mode": "sync",                 // sync (default) | queue
      "output": "url",                // url (default) | binary
      "format": "png",                // png (default) | jpeg | webp | pdf
      "width": 1280,                  // 320-3840, default 1280
      "height": 800,                  // 240-2160, default 800
      "full_page": false,             // capture full scroll height
      "dark": false,                  // emulate prefers-color-scheme: dark
      "scale": 1,                     // 1-3, device pixel ratio
      "quality": 80,                  // 1-100, jpeg/webp only
      "delay": 0,                     // 0-10000 ms extra wait after load
      "clip_x": 0,                    // crop: left edge,   CSS px (>=0)
      "clip_y": 0,                    // crop: top edge,    CSS px (>=0)
      "clip_width": 640,              // crop: width,       CSS px (>=1)
      "clip_height": 400,             // crop: height,      CSS px (>=1)
      "resize_width": 200,            // scale output, 1-3840 px
      "resize_height": 150            // scale output, 1-2160 px
    }

Responses:
- mode=sync, output=binary  -> 200 with the file bytes
- mode=sync, output=url     -> 201 JSON, data.image_url is the hosted file
- mode=queue                -> 202 JSON, poll data.links.self until
                               data.status == "completed", then fetch
                               data.links.download (binary) or data.image_url
- capture failure           -> 502 JSON with screenshot.error
- validation failure        -> 422 JSON with errors

### Thumbnails (crop & resize)

Two independent steps, made for thumbnails:

- Crop with `clip_x` / `clip_y` / `clip_width` / `clip_height` — a rectangle of
  the rendered page in CSS pixels (measured before `scale`), captured via the
  browser's native clip. All four are required together; `clip_x`/`clip_y` start
  at 0, width/height are at least 1. Do not combine with `full_page`.
- Resize with `resize_width` and/or `resize_height` — scales the finished image
  after capture. Pass one to preserve aspect ratio, both to force exact
  dimensions. Ignored when `format=pdf`.

Crop then resize to grab a region and shrink it — e.g. the top-left card of a
page, scaled down to a 200px-wide thumbnail:

    GET https://shot.amazz.ing?url=https://example.com&clip_x=0&clip_y=0&clip_width=640&clip_height=400&resize_width=200

### Status

    GET https://amazz.ing/api/screenshots/{id}

JSON status document. `status` is pending | processing | completed | failed.

### Download

    GET https://amazz.ing/api/screenshots/{id}/download

The file bytes once completed; 409 JSON while pending, 502 JSON if failed.

## Notes for agents

- No authentication. Do not send API keys; there is nowhere to put them.
- Rate limit: 60 requests/minute per IP. Use mode=queue for bulk work.
- Captures are pruned after 48 hours. Download what you need.
- Errors are always JSON with a `message` field. The HTTP status tells the story.
- GET /shot is the same engine as the POST endpoint; every parameter above
  works as a query string parameter (e.g. &full_page=true&format=jpeg).