# Creating PDFs

This guide will show you how to create PDFs using the ScreenshotBuddy API. Send `pdf=true` alongside the parameters below.

> Make sure you have read the [quickstart guide](https://screenshotbuddy.io/documentation.md). It will help you understand how to authenticate and make requests to the API.

## Options

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `url` | string | yes |  | The URL of the page to render. It must start with `http://` or `https://`, be at most `2048` characters long, and point at a publicly reachable host. Private, loopback and internal addresses are refused. |
| `pdf` | boolean | no | `false` | Set this to `true` to render a PDF instead of an image. It changes which other parameters are accepted, so see [creating PDFs](https://screenshotbuddy.io/documentation/creating-pdfs.md) for the options that belong to that mode. Defaults to `false`. |
| `landscape` | boolean | no | `false` | Whether to use landscape orientation. Defaults to `false` (portrait). PDFs only; sending it without `pdf` is rejected. A screenshot is shaped by `width` and `height` instead. |
| `paperFormat` | string | no | `a4` | The paper format. Possible values are `letter`, `legal`, `tabloid`, `ledger`, and `a0` through `a6`. Defaults to `a4`. PDFs only; sending it without `pdf` is rejected. Use `format` to set the image format of a screenshot. |
| `width` | number | no |  | The viewport width of a screenshot, or the paper width of a PDF, between `1` and `10000`. Must be used together with `height`. For a PDF it overrides `paperFormat` and is read in the unit set by `marginUnit`. |
| `height` | number | no |  | The viewport height of a screenshot, or the paper height of a PDF, between `1` and `10000`. Must be used together with `width`. For a PDF it overrides `paperFormat` and is read in the unit set by `marginUnit`. |
| `marginTop` | number | no |  | Top margin, between `0` and `1000`, in the unit set by `marginUnit`. All four margins (`marginTop`, `marginRight`, `marginBottom`, `marginLeft`) have to be set together. PDFs only; sending a margin without `pdf` is rejected. |
| `marginRight` | number | no |  | Right margin, between `0` and `1000`, in the unit set by `marginUnit`. Set it together with the other three margins. PDFs only; sending a margin without `pdf` is rejected. |
| `marginBottom` | number | no |  | Bottom margin, between `0` and `1000`, in the unit set by `marginUnit`. Set it together with the other three margins. PDFs only; sending a margin without `pdf` is rejected. |
| `marginLeft` | number | no |  | Left margin, between `0` and `1000`, in the unit set by `marginUnit`. Set it together with the other three margins. PDFs only; sending a margin without `pdf` is rejected. |
| `marginUnit` | string | no | `mm` | The unit for the margins and for a custom paper size. Possible values are `mm`, `cm`, `in` and `px`. Defaults to `mm`. PDFs only; sending it without `pdf` is rejected, because a screenshot's `width` and `height` are viewport pixels. |
| `scale` | number | no | `1` | In this mode, between `0.1` and `2`. The scale of the rendering, between `1` and `3` for screenshots and between `0.1` and `2` for PDFs. Screenshots take whole numbers only, because the browser renders at whole device scale factors; PDFs take fractions. Defaults to `1`. A value outside the range of the mode you are in is rejected. |
| `cache` | boolean | no | `true` | Whether an identical repeat of this request may be answered with the rendering we already made, and whether this rendering is kept for the next one. Defaults to `true`. A cached answer costs no credit, says so with `X-Cache: HIT`, and is counted against the account's cached-answer limit rather than against its renders; send `cache=0` to render the page again, which costs a credit and a render slot as any render does. Entries belong to your own account. See [caching](https://screenshotbuddy.io/documentation/caching.md) for the whole picture. |
| `cacheTtl` | integer | no | `86400` | How long the rendering is kept, in seconds, between `60` and `2592000` (thirty days). Defaults to `86400`. Sending it with `cache=0` is rejected, because there is no lifetime to set on a rendering that is not being kept. |

The `delay` parameter is not accepted for PDFs. The PDF renderer has no way to wait a fixed amount of time before it prints, so a request that combines `delay` with `pdf` is rejected rather than rendered without the wait you asked for.

The screenshot options are a different set, listed on the [taking screenshots](https://screenshotbuddy.io/documentation/taking-screenshots.md) page.

A PDF is a rendering of whatever the server served, exactly as a screenshot is. A login wall, a `404` page or a bot challenge is printed as faithfully as the page you meant, and a `4xx` or `5xx` target still costs a credit. What a PDF answer does not carry is `X-Target-Status`: the renderer reports nothing at all about the page behind a PDF render, so the document itself is the only thing that says what was captured. The screenshot page explains the header under [what the target answered](https://screenshotbuddy.io/documentation/taking-screenshots.md).

## The playground

Switch the playground at https://screenshotbuddy.io/playground to PDF mode to pick a paper format, flip to landscape, and read the generated document in the browser before you write a single line of code.