# Screenshot (URL) API

> Render any web page to JPEG, PNG or PDF at a chosen viewport.

Loads the page in a headless Chromium instance, waits for `delay` seconds so late-loading content settles, and saves a capture. The reply carries the URL of the saved file under `/screen/url/s/`.

- **Endpoint:** `POST https://api.zactonz.com/screen/url/`
- **Category:** Media
- **Version:** 1
- **Status:** stable
- **Authentication:** `Authorization: Bearer YOUR_API_KEY`
- **Reference page:** https://developers.zactonz.com/apis/screenshot-url/

## Parameters

Send parameters as `application/x-www-form-urlencoded` form fields in the request body.

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string | yes |  | Absolute URL of the page to capture. |
| `width` | integer | no | `1280` | Viewport width in pixels, 200 to 3840. Values outside the range are clamped. Default 1280. |
| `height` | integer | no | `1024` | Viewport height in pixels, 150 to 4320. Values outside the range are clamped. Default 1024. |
| `format` | enum | no | `jpeg` | Output type. `jpeg` (default), `png`, `webp`, or `pdf` for a paged document. Allowed values: `jpeg`, `png`, `webp`, `pdf`. |
| `quality` | integer | no | `100` | JPEG quality from 1 to 100. Default 100. Ignored for other formats. |
| `delay` | integer | no | `5` | Seconds to wait after the page has loaded before capturing, 0 to 15. Default 5. |
| `download` | string | no |  | Any value. Stream the file instead of returning JSON. |
| `orientation` | enum | no | `portrait` | PDF only. Allowed values: `portrait`, `landscape`. |
| `paperWidth` | number | no | `6` | PDF only. Paper width in inches. |
| `paperHeight` | number | no | `6` | PDF only. Paper height in inches. |
| `marginTop` | number | no | `0.4` | PDF only. Also `marginBottom`, `marginLeft`, `marginRight`. Inches. |
| `scale` | number | no | `1` | PDF only. Render scale. |

## Example request

```bash
curl -X POST "https://api.zactonz.com/screen/url/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "url=https://zactonz.com" \
  --data-urlencode "width=1280" \
  --data-urlencode "height=1024" \
  --data-urlencode "format=jpeg" \
  --data-urlencode "quality=100" \
  --data-urlencode "delay=5" \
  --data-urlencode "orientation=portrait" \
  --data-urlencode "paperWidth=6" \
  --data-urlencode "paperHeight=6" \
  --data-urlencode "marginTop=0.4" \
  --data-urlencode "scale=1"
```

## Response

Metadata and the URL of the saved capture.

| Field | Type | Description |
|---|---|---|
| `status` | string | `"200"` on success (a string). See status codes below. |
| `width` | integer | Viewport width that was used. |
| `height` | integer | Viewport height that was used. |
| `data` | string | Absolute URL of the saved image or PDF, or an error message. |

```json
{
    "status": "200",
    "width": 1280,
    "height": 1024,
    "data": "https://api.zactonz.com/screen/url/s/Kd8Qw_213pLm2Xc9Vb1Tn.jpeg"
}
```

## Status codes

The outcome is reported in the JSON `status` field. General rules: https://developers.zactonz.com/apis/errors.md

| status | Meaning | Description |
|---|---|---|
| `200` | OK | The capture was saved. Note that this endpoint returns `status` as a string. |
| `400` | Bad request | `url` was missing, or `quality` was `0` for JPEG output. |
| `502` | Not rendered | The browser could not load or capture the page within the time limit. |

## Notes

Rendering a page takes a few seconds; allow a client timeout of at least 60 seconds. Pass `download=1` to receive the file bytes directly (with `Content-Disposition: attachment`) instead of a JSON reply.

The PDF options (`orientation`, margins, paper size and `scale`) only apply when `format=pdf`. Margins and paper dimensions are in inches.