Introduction

Restpack HTML to PDF API is an easy to use RESTful web service that can capture live web pages and deliver the structured view as a PDF document. The service sits on a fully functional browser rendering engine with rich html / css / js capabilities.

Quick Start

Here are some code samples you can use. Don't forget to obtain a token here.

You can find detailed usage information below.

Authentication

With each API call, you must provide an authentication token. To create a new access token please refer to user tokens page on your account dashboard.

You can either provide the access token within the querystring or as a header.

• If you wish to use the querystring method. Provide the token as access_token querystring parameter. As in https://restpack.io/api/html2pdf/v7/convert?access_token={TOKEN}
• In case you want to use a header, please provide the access token in X-Access-Token header.

Errors

Access token errors are represented in 4xx class HTTP errors.

• 401 - in case no access token is provided.
• 402 - when the account balance is not sufficient for this API call.
• 403 - when the access token is not valid / revoked.

Response Modes

By default, the API returns the raw document itself. This is the easiest way to consume the API. You can stream the result back to a file, to a web request or any other storage service. Meanwhile, it is possible to receive a JSON response using json: true parameter.

When you request a JSON response, API will return a JSON object with a publicly accesible URL to the resulting rendered pdf. You can use this document directly on your websites or access the file from this URL and save it elsewhere. Using this URL is not counted against your API call limits and it is being hosted over our CDN servers.

JSON responses contain an image URL, that points to the PDF and a cached field to indicate if the document is being served from cache, height and width of the captured URL, HTTP status code as remote_status, and execution (rendering + converting) time as run_time parameter.

{
  "cached": true,
  "height": 768,
  "width": 1280,
  "image": "https://cdn.restpack.io/a/cache/pdf/96f6cd877429e5b37e96533cff96c52ff10fc687d537d6cad72f1f2795c020ec",
  "remote_status": 200,
  "run_time": 1166,
  "url": "https://google.com"
}

Endpoint

{
  "cached": true,
  "height": 768,
  "width": 1280,
  "image": "https://cdn.restpack.io/a/cache/pdf/96f6cd877429e5b37e96533cff96c52ff10fc687d537d6cad72f1f2795c020ec",
  "remote_status": 200,
  "run_time": 1166,
  "url": "https://google.com"
}

{
  "days": [
    {
      "count": 6,
      "day": "2019-05-06T00:00:00Z"
    },
    {
      "count": 9,
      "day": "2019-05-07T00:00:00Z"
    },
    {
      "count": 1,
      "day": "2019-05-08T00:00:00Z"
    },
    {
      "count": 31,
      "day": "2019-05-15T00:00:00Z"
    },
    {
      "count": 1,
      "day": "2019-05-16T00:00:00Z"
    },
    {
      "count": 3,
      "day": "2019-05-17T00:00:00Z"
    },
    {
      "count": 1,
      "day": "2019-05-18T00:00:00Z"
    }
  ],
  "from": "2019-05-01T00:00:00Z",
  "limit": 1000,
  "to": "2019-05-20T11:58:06.604980595Z",
  "total": 52,
  "workers": 1
}

Features

Headers and Footers

Captured documents do not contain any header or footer by default. If you wish to add page headers or footers you can provide an HTML template and the API automatically handles injection for you.

Note that we refer to these html snippets as templates because they can contain placeholders for dynamic data. For example if you wish to show the current page number somewhere within your header, you can use <span class="pageNumber"></span> element. The pageNumber class instructs our engine to inject the current page number in that element.

Available class names for dynamic data:

• pageNumber: Current page number
• totalPages: Total number of pages in the document
• url: Captured page URL
• title: Document title
• date: Date of capture in UTF

Also note that you must have a pdf_margins paramater in order to use the header / footer functionality. The header and footer show up inside your top and bottom margins, you need to provide appropriate space for the headers and footers to render.

While the header and footer sections can be styled using CSS, they do not share the main pages css styles. The best way to style header and footer elements is to use inline styles as in <div style="background: red">...</div>.

Delay

By default, capturing engine waits for the page load and then 500 more milliseconds for initial javascripts to settle their rendering. You can control this duration using delay parameter (in milliseconds) from instantaneous to 20 seconds.

TTL

The API caches generated PDF documents up to a specified time period. If you request a PDF of a previously cached web page, result will be provided from the cache. It is possible to control the duration of cache using cache_ttl parameter (in seconds)

In addition to setting a cache_ttl, it is possible to use fresh=true prameter to invalidate cache and capture a new PDF.

HTTP Headers

While the service uses reasonable defaults for the request headers, you can customize them as you wish.

• user_agent parameter customizes the User-Agent header.
• headers parameter is the freeform one. You can pass any string containing headers seperated by \n.