Documentation

How to use PDFBlade

Overview

Welcome to the PDFBlade documentation! This page and its sections contain all of the information you need to get started consuming the API, converting your website links and raw HTML to formatted PDFs.

Use the links in the sidebar to skip through the different sections of this documentation, or continue scrolling down.

Getting Started

In order to start using the API, you'll have to register for an account on the website. You can click the 'Sign Up' button at the very top-right of this page, or go to the link here.

Once your account has been created, you'll be taken to the dashboard. From there, you can view your API access key by clicking the 'Show Key' button in the dashboard menu. This will reveal the key that you'll need to make calls to the API, as we'll explain further down.

Additionally, when your account was created, you were gifted 100 free conversion credits. These are used to make calls to the API, and are spent when a website or raw HTML has been converted successfully to a PDF. Only a single credit is used per conversion regardless of any options set, and by default you'll be notified via email when your account starts to run low. Additional conversion credits can then be purchased through your dashboard in the billing section.

Basic Usage

After you've obtained your authorization key, you can start making calls to the API right away. Authentication is possible in two ways:

  • By setting the x-api-key header and using your key as the value
  • By including a key parameter in the request with its value

Calls to the API may also be made via either POST or GET requests. The command below is probably the most basic call you can make to the API. After it completes the GET request, it will return back an Amazon S3 url containing google.com converted into a PDF.

Bash
curl -v https://pdfblade.com/api/convert/https://google.com&key=my-key-here&store=true

And that same command as a POST request looks like this:

Bash
curl -v --data="key=my-key-here&store=true&url=https://google.com" https://pdfblade.com/api/convert

Parameter Details

Listed below are all of the possible parameters you can include in your calls to the PDFBlade API, along with their details. All of them work as either parts of the body of a POST request, or tacked on as query variables if you're using the GET request method.

If you have a request for a new option or any suggestions for the parameters that are currently available, please don't hesitate to contact us at hello@pdfblade.com.

store

  • Required: no
  • Type: boolean
  • Default: false

Used to determine whether or not the compiled PDF is cached and stored in Amazon S3. If you set this to true, we will store your PDF on our Amazon S3 bucket and return back a URL that remains active for 48 hours. Otherwise, you will get back the full PDF binary as a response. You can check your account dashboard to see if stored files are still active.

format

  • Required: no
  • Type: string
  • Default: Letter

The paper format and size of the individual pages in the compiled PDF. Available options are as follows: Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, or A6

margins

  • Required: no
  • Type: string
  • Default: 0

The margins (in inches) that are set around the individual pages in the compiled PDF. You can pass in a single value like 3, which will give you a margin of 3 inches around the document. Alternatively, you can use two values separated by a comma like 3,5 for top/bottom and left/right respectively, or four like 1,3,1,5 for top, right, bottom, and left respectively.

background

  • Required: no
  • Type: boolean
  • Default: false

Determines whether the background of the website is rendered in the PDF. By default, it is not. Set this to true in order to include it in your PDFs.

landscape

  • Required: no
  • Type: boolean
  • Default: false

Determines whether the rendered PDF will be in landscape mode. By default, PDFs are returned in portrait mode, but set this to true to change it to landscape.

pages

  • Required: no
  • Type: string
  • Default: (null)

Allows you to control what pages are returned in the compiled PDF. You can pass in a single value like 2 which will only return the second page, or a range of pages like 3-5. If you request a page that doesn't exist in the final PDF, it will return blank.

media

  • Required: no
  • Type: string
  • Default: screen

Gives you the ability to spoof the media agent that the site or HTML is rendered with. Possible values are screen, speech, and print.

userAgent

  • Required: no
  • Type: string
  • Default: Chromium

Gives you the ability to spoof the browser's User Agent string sent to the requested site being converted.

timeout

  • Required: no
  • Type: integer
  • Default: 30

Sets a limit (in seconds) of how long the renderer will wait for the requested site before timing out and returning back a response. If a site times out before it is rendered, a conversion credit will not be used. The minimum for this is 5 and the maximum is 99.

delay

  • Required: no
  • Type: integer
  • Default: 0

Sets a delay (in seconds) that the renderer will wait before beginning to convert the site to a PDF. The minimum for this is 0 and the maximum is 99.

images

  • Required: no
  • Type: boolean
  • Default: true

Determines whether or not the renderer will include images in the compiled PDF. Set this to false to hide all images.

javascript

  • Required: no
  • Type: boolean
  • Default: true

Determines whether or not the renderer will include and run JavaScript on the requested website before compiling a PDF. Set this to false to block all JavaScript on the requested website.

links

  • Required: no
  • Type: boolean
  • Default: true

Determines whether or not the renderer will include links in the compiled PDF. Set this to false to disable clickable links that were present on the website.

auth

  • Required: no
  • Type: string
  • Default: (null)

Passes through a basic http authentication to the requested website. Use the format username:password when making calls that contain this option.

css

  • Required: no
  • Type: string
  • Default: true

The value of this should be a fully-qualified URL that points to a CSS stylesheet. This is injected into the head of the requested website and can let you affect the styling of the rendered PDF.

Code Examples

Below you'll find a few examples of PDFBlade implemented in a few popular programming languages and frameworks. If you'd like to see a particular example, or know of a wrapper package for one of these examples, please let us know at hello@pdfblade.com.

PHP
use GuzzleHttp\Client;

$client = new Client();
$response = $client->request('POST', 'https://pdfblade.com/api/convert', [
    'json' => [
        'key'    => 'my-key-here',
        'store'  =>  true,
        'url'    =>  'https://google.com',
        'images' =>  false,
        'margins' => '1,3'
    ]
]);
$pdfUrl = $response->getBody();

return $pdfUrl;
JavaScript
import axios from 'axios';

axios.post('https://pdfblade.com/api/convert', {
    key: 'my-key-here',
    store: true,
    url: 'https://google.com',
    images: false,
    margins: '1,3'
})
.then((response) => {
    alert(response.data);
})
.catch((error) => {
    console.error(error);
});
C#
using System.Net;
using System.Collections.Specialized;

using (var wb = new WebClient())
{
    var data = new NameValueCollection();
    data["key"] = "my-key-here";
    data["store"] = true;
    data["url"] = "https://google.com";
    data["images"] = false;
    data["margins"] = "1,3";

    var response = wb.UploadValues("https://pdfblade.com/api/convert", "POST", data);
    string pdfUrl = Encoding.UTF8.GetString(response);
}
Python
import requests

data = {'key': 'my-key-here',
        'store': true,
        'url': 'https://google.com',
        'images': false,
        'margins': '1,3'}

r = requests.post(url = 'https://pdfblade.com/api/convert', data = data)

pdf_url = r.text

File Storage

As stated earlier in the parameter description, when you set the store option to true the returned PDF is stored in our Amazon S3 bucket and you get a URL returned as the response from the API call. This URL is active for 48 hours from when you made the request, and after that time is up it is deleted from S3 and no longer active.

While the file is active, please feel free to view it and share it as an alternative to having to recompile a PDF multiple times. Additionally, you can save the file before it expires to ensure longevity.

In your dashboard, you can see if a file is stored for a particular conversion, determine if it's still active or not, and view the link that it's stored at if it is.

Support

If you have any questions about this documentation, need help using the PDFBlade API, or have comments on the platform in general, please don't hesitate to reach out to us.

We're available by email at hello@pdfblade.com and on Twitter @pdfblade.