Creating PDFs

This guide will show you how to create PDFs using the ScreenshotBuddy API.

Make sure your have read the quickstart guide. It will help you understand how to authenticate and make requests to the API.

Options

  • Name
    url
    Type
    string
    Description

    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.

  • Name
    pdf
    Type
    boolean
    Description

    Set this to true to render a PDF instead of an image. It changes which other parameters are accepted, so see creating PDFs for the options that belong to that mode. Defaults to false.

  • Name
    landscape
    Type
    boolean
    Description

    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.

  • Name
    paperFormat
    Type
    string
    Description

    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.

  • Name
    width
    Type
    number
    Description

    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.

  • Name
    height
    Type
    number
    Description

    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.

  • Name
    marginTop
    Type
    number
    Description

    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.

  • Name
    marginRight
    Type
    number
    Description

    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.

  • Name
    marginBottom
    Type
    number
    Description

    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.

  • Name
    marginLeft
    Type
    number
    Description

    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.

  • Name
    marginUnit
    Type
    string
    Description

    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.

  • Name
    scale
    Type
    number
    Description

    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.

  • Name
    cache
    Type
    boolean
    Description

    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 for the whole picture.

  • Name
    cacheTtl
    Type
    integer
    Description

    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.

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.

Try PDF mode in the playground

Switch the 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.

Open the playground