Documentation
API Documentation
This is the Documentation Page for Insta-PDF, a REST API that generates and returns PDF files from a URL or HTML source.
Getting started
API Access Key & Authentication
After signing up, an API access key will be sent to your email adress. Authentication is done via HTTP Bearer Auth Token in the header.
To connect you have to include a header in each of your requests with the following key-value pair:
- ‘Authorization‘: ‘Bearer <your API key>‘
const request = require("request");
const options = {
method: "POST",
url: "https://api.insta-pdf.com/v1/convert",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR-API-KEY"
},
body: {},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});Accessing secure sites/member areas
If you want to convert a protected website/member area to PDF, you have the following options:
- Pass the page as raw HTML to the API with the html parameter instead of using the url parameter. You can use https to access our API to ensure your data is secure.
- Secure your content with basic HTTP authentication and use the username and password parameters in the API call.
- Secure your content with a login form and pass the form fields and values to the API so we can access the protected area.
Parameters | Description |
username | Username for basic HTTP access authentication |
password | Password for basic HTTP access authentication |
form_url | URL of a login page that you want us to use and post the form_fields to |
form_fields | Array with form fields and values |
HTTPS encryption
https://api.insta-pdf.comIn order to connect to our API securely, please use industry-standard HTTPS (SSL) encryption. To connect via HTTPS, make sure you use https protocol in your API request.
API errors
If your request to the API does not succeed, you will get an error response with a code that you can look up on this page to see what it means.
Code | Description |
200 OK | Succesful conversions |
400 Bad Request | You didn't specify anything to convert
|
401 Authorization required | Invalid or not specified license key |
429 Too Many Requests | You have overrun a usage limit for your plan
|
503 Service unavailable | You are sending multiple requests at the same time to the API from the same IP address
|
504 Conversion Time Exceeded | Your webpage takes too long to convert. (max. 60 seconds/conversion is allowed) |
520 Invalid page size or margins | The page is too small or too large to print on, set different page/margin sizes |
530 DNS Error for URL | The domain of the URL can not be found |
If you can’t find a solution to your problem, please contact us.
API endpoints
HTML to PDF Conversion
const request = require("request");
const options = {
method: "POST",
url: "https://api.insta-pdf.com/v1/convert",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR-API-KEY"
},
body: {},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});(POST) https://api.insta-pdf.com/v1/convert
This endpoint is responsible for the PDF conversions.
Parameters of the HTML to PDF converter endpoint
In this section you can learn about all the setting options of InstaPDF. Use them to change the characteristics of your PDF by attaching any parameter listed in the tables below to your request.
To set the parameters for your HTML to PDF conversion, include the key-value pairs listed in the tables below in your API request’s body.
Example (we set the page size to A4, with 50px top and bottom margins):
const request = require("request");
const options = {
method: "POST",
url: "https://api.insta-pdf.com/v1/convert",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR-API-KEY"
},
body: {
"page_size": "A4",
"margin_top": 50px,
"margin_bottom": 50px
},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
Page Dimensions
Headers & Footers
Parameters | Description |
page_size | A1/A2/A3/.../Letter/Tabloid/.... See the full list here |
page_width | Page width in mm (millimeters), cm (centimeters), in (inches), px (pixels) or pt (points) |
page_height | Page height in mm (millimeters), cm (centimeters), in (inches), px (pixels) or pt (points) |
margin_top | Top margin in mm (millimeters), cm (centimeters), in (inches), px (pixels) or pt (points) |
margin_bottom | Bottom margin in mm (millimeters), cm (centimeters), in (inches), px (pixels) or pt (points) |
margin_left | Left margin in mm (millimeters), cm (centimeters), in (inches), px (pixels) or pt (points) |
margin_right | Right margin in mm (millimeters), cm (centimeters), in (inches), px (pixels) or pt (points) |
orientation | Sets the orientation of the page to vertical/horizontal |
Parameter | Description |
header_html | HTML code for header
|
header_text | Text in the header (Do not use it together with header_html parameter) |
header_align | Alignment property of the header text Options: left, center, right. Default: left |
header_margin | Margin at the top of the page for the footer placement in mm, cm, in,px or pt Default: 0px |
header_start_at | The page you want start showing the header on Default: 1 |
footer_html | HTML code for footer |
footer_text | Text in the footer (Do not use it together with footer_html parameter) |
footer_align | Alignment property of the footer text Options: left, center, right. Default: left |
footer_margin | Margin at the bottom of the page for the footer placement in mm, cm, in,px or pt Default: 0px |
footer_start_at | The page you want start showing the footer on Default: 1 |
Conversion parameters
Parameter | Description |
html | The URL of the website you want to convert to a PDF file |
url | The raw HTML code you want to convert to a PDF file |
css | Use custom CSS to style the page, can be a string and a URL |
filename | Choose a name for your PDF file |
no_background | Do not show the background image/color of the website in the PDF file |
no_images | Do not include images of the webpage in the PDF |
no_js | Convert the page with JavaScript switched off |
no_css | Convert the page with CSS switched off |
no_ads | Remove ads |
no_forms | Do not include forms in the PDF |
no_blank_pages | Remove blank pages |
grayscale | Convert to a grayscale PDF |
delay | Enables you to specify a custom delay time (in milliseconds) before the PDF is generated. It could be useful if certain contents of the website appear after the initial page load. |
Watermarks
Parameter | Description |
wm_image | URL of the watermark image |
wm_text | Text of the watermark |
wm_font_size | Font size of watermark text (in points) |
wm_font | Font face for the text watermark, for example Ariel |
wm_font_color | Font color of the watermark text |
wm_font_bold | Set to true to make the watermark text bold. |
wm_font_italic | Set to true to make the text style italic. |
wm_x | The horizontal position of the watermark |
wm-y | The vertical position for the watermark
|
wm_img_width | Width of the watermark in mm, cm, in,px or pt |
wm_img_height | Height of the watermark in mm, cm, in,px or pt |
wm_opacity | Set the opacity of the watermark Between 0 and 1 (1 means fully opague) |
wm_angle | Angle of rotation between 0 and 360 |
API Usage tracking
const request = require("request");
const options = {
method: "GET",
url: "https://api.insta-pdf.com/v1/usage",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR-API-KEY"
},
body: {},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});(GET) https://api.insta-pdf.com/v1/usage
This endpoint will give you a response showing your plan details and usage (tied to current billing cycle) .
- date range of usage
- limit field: your plans monthly API calls
- total field: your used API calls
List of created PDFs
const request = require("request");
const options = {
method: "POST",
url: "https://api.insta-pdf.com/v1/list?from=DD-MM-YY&to=DD-MM-YY&limit=100&page=1",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR-API-KEY"
},
body: {},
json: true
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});(GET) https://api.insta-pdf.com/v1/list?from=DD-MM-YY&to=DD-MM-YY&limit=100&page=1
This endpoint lists your created PDFs in the specified time interval.