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 20 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-keyheader and using your key as the value - By including a
keyparameter 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.
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:
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.
type NEW!
- Required:
no - Type:
string - Default:
pdf
Used to determine whether or not to render the URL/HTML as a full PDF or as an image.
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 miliseconds) that the renderer will wait before beginning to convert the site to a PDF. The minimum for this is 0 and the maximum is 15000.
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.
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.
scale NEW!
- Required:
no - Type:
integer - Default:
0.75
Sets the scale of the returned browser view to better accommodate some PDF formats.
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 (handy to remove pop ups and other browser annoyances.). Set this to false to block all JavaScript on the requested website.
cors NEW!
- Required:
no - Type:
boolean - Default:
false
If you are experiencing any CORS related issues, you can set this option to true to disable web security settings for the renderer.
lang NEW!
- Required:
no - Type:
string - Default:
en
If you need to reder your file in specific browser language, set this option to the browser language code desired. The following language codes are supported (if you need another language code, please message us).
en,en-us,en-gb,en-au,en-ca,en-nz,en-ie,es,de,ja,da,nl,fr,el,he,hi,it,is,ko,no,pl,pt,ro,ru,sv,th,tr,uk
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.
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;
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);
});
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);
}
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.