HTML PDF API documentation

Usage
API documentation
- API endpoints
- Authentication
- PDF
- Image
- Credits
- Assets
- Error responses
- Appendix

API endpoints

Base url for api is: https://htmlpdfapi.com/api/v1/

URL	Method	Description
/pdf	`POST`	Generate a PDF
/image	`POST`	Generate an image
/credits	`GET`	Get credits count
/assets	`GET`	List all assets
/assets	`POST`	Create a new asset
/assets	`PUT`	Update an existing asset
/assets/:id	`GET`	Get an asset by ID
/assets/:id	`DELETE`	Delete an asset by ID

Authentication

All requests must be authenticated for access to API. Authentication is done via HTTP headers.

Example

headers["Authentication"] = "Token <your token>"

Authentication header value must have following format: "Token" + " " + <token string>

PDF

Parametar	Default	Values	Description
`url`			Url of a page for conversion. Must start with http or https.
`file`			File for conversion. Accepted types are: html, htm, zip, tar.gz, tgz, tar.bz2. (more info)
`html`			HTML string. eg. <h1>Hello world</h1>
`callback`			Callback URL is used to receive `POST` request with PDF file from HTML PDF API service. (more info)
`filename`	out.pdf		Name of a generated PDF file
`disposition`	attachment	attachment, inline	Content-Disposition of a returned PDF file
`group`			Name of a group. E.g. if you have multiple clients under the same account and you want to know the total cost per client. Group can be added in administration.
`engine_version`	12	11, 12	Version of html to pdf engine.

`username`			Username for HTTP basic authentication.
`password`			Password for HTTP basic authentication.

`encoding`	utf-8		Text encoding in PDF.
`images`	true	boolean	Load and print images.
`javascript`	true	boolean	Enable javascript execution.
`javascript_delay`	200	min:1, max:800	Wait a few milliseconds for javascript to finish.
`zoom`	1		Browser page zoom factor. Float format. e.g. 1.2
`smart_shrinking`	1	boolean	Disable smart shrinking to have more accurate dimensions


`dpi`	75	Min:75, Max:149	DPI of virtual screen when converting document to PDF document.
`image_dpi`	600		Embedded images are scaled down to a defined DPI
`image_quality`	94		Compress jpeg images to a defined quality
`lowquality`	false		Generate a low quality PDF document from HTML with a smaller output size.

`orientation`	portrait	portrait, landscape	Set the orientation of all pages in PDF.
`page_size`	A4	page sizes	One of the standard page sizes.
`page_width`			Custom page width. Must be set in combination with `page_height`.
`page_height`			Custom page height. Must be set in combination with `page_width`
`margin_top`	10mm	units	Top margin of the PDF document
`margin_right`	10mm	units	Right margin of the PDF document
`margin_bottom`	10mm	units	Bottom margin of the PDF document
`margin_left`	10mm	units	Left margin of the PDF document

`title`	HTML title		Title of the generated PDF file. Defaults to title of the HTML document.
`outline`	true	boolean	Create outline / index in generated PDF document.
`outline_depth`	4		Outline depth. PDF outline is created with HTML heading tags (h1,h2, h3, h4, h5, h6).
`background`	true	boolean	Print background in the PDF document.
`internal_links`	true	boolean	HTML anchor linking in PDF document.
`external_links`	true	boolean	External links in the PDF document.
`page_offset`	0		Starting page number in the PDF document.

`use_print_media_type`	false	boolean	Use print media type instead of screen. By default API uses stylesheets with `media="screen"` this forces it to use only stylesheets with `media="print"` .
`viewport_size`	800x600	<width>x<height>	Browser viewport in pixels e.g. (1280x800)

`header`			Header HTML. Variables in header and footer
`footer`			Footer HTML. Variables in header and footer
`header_spacing`		min:1	Spacing between header and content in millimeters (mm)
`footer_spacing`		min:1	Spacing between footer and content in millimeters (mm)

You can send only one of following parameters: url, file, html.

Response

Successful response will return PDF file.

Example

curl -H 'Authentication: Token <your token>' \
-d 'url=http://htmlpdfapi.com/examples/example.html' \
'https://htmlpdfapi.com/api/v1/pdf' > result.pdf

For more examples check out usage page

Image

Parametar	Default	Values	Description
`url`			Url of a page for conversion. Must start with http or https.
`file`			File for conversion. Accepted types are: html, htm, zip, tar.gz, tgz, tar.bz2. (more info)
`html`			HTML string. eg. <h1>Hello world</h1>
`callback`			Callback URL is used to receive `POST` request with PDF file from HTML PDF API service. (more info)
`filename`	out.pdf		Name of a generated PDF file
`disposition`	attachment	attachment, inline	Content-Disposition of a returned PDF file
`group`			Name of a group. E.g. if you have multiple clients under the same account and you want to know the total cost per client. Group can be added in administration.
`engine_version`	12	11, 12	Version of html to pdf engine.

`username`			Username for HTTP basic authentication.
`password`			Password for HTTP basic authentication.

`encoding`	utf-8		Text encoding in PDF.
`images`	true	boolean	Load and print images.
`javascript`	true	boolean	Enable javascript execution.
`javascript_delay`	200	min:1, max:800	Wait a few milliseconds for javascript to finish.
`zoom`	1		Browser page zoom factor. Float format. e.g. 1.2
`smart_shrinking`	1	boolean	Disable smart shrinking to have more accurate dimensions
`ext`	png	png, jpg, gif	Image extension. Output format of the image.
`quality`	94	0-100	Quality of the output image.
`width`			Image width in pixels
`height`			Image height in pixels
`crop_w`			Width of the cropping area in pixels
`crop_h`			Height of the cropping area in pixels
`crop_x`			X coordinate of the cropping area in pixels
`crop_y`			Y coordinate of the cropping area in pixels

Response

Successful response will return Image file.

Example

curl -H 'Authentication: Token <your token>' \
-d 'url=http://htmlpdfapi.com/examples/example.html' \
'https://htmlpdfapi.com/api/v1/image' > result.png

Credits

Get the current number of credits.

URL	Method	Description
/credits	`GET`	Get a credits count

Response

Succesful response will return the number of credits.

Example

curl -H 'Authentication:Token <your token>' \
'https://htmlpdfapi.com/api/v1/credits'

Assets

Assets allow you to upload a file and use it as a local file on the server in your templates. This greatly increases the speed of the PDF export.

We expose a special varibable {{assets_path}} which links to a directory with all of your assets.

Example

<img src="{{assets_path}}/my_image.jpg" />

Assets LIST

Get list of all assets uploaded to server.

URL	Method	Description
/assets	`GET`	List all assets

Response

Succesful response will return JSON object of all assets with status 200. Size is defined in bytes.

Response example

[
  {
    "id": "222fb2fad512753f06000002",
    "name": "font_bauhausb.ttf",
    "mime": "application/x-font-ttf",
    "size": 40608
   },
   {
    "id": "222ad588db9acd23480001c4",
    "name": "logo_hi_quality.png",
    "mime": "image/png",
    "size": 611483
   }
]

Example

curl -H 'Authentication:Token <your token>' \
'https://htmlpdfapi.com/api/v1/assets'

Assets CREATE

Upload new assets to server

URL	Method	Description
/assets	`POST`	Create new asset

Parametars

Parametar	Default	Values	Description
`file`			File for upload. Accepted types are: js, css, png, jpg, jpeg, gif, ttf, otf, woff

Response

Succesful response will return JSON object of uploaded file with status 201. Size is defined in bytes.

Response example

{
  "id": "fb2222fad512753f06000002",
  "name": "my_image.jpg",
  "mime": "image/jpeg",
  "size": 40608
}

Example

curl -H 'Authentication:Token <your token>' \
-F 'file=@my_image.jpg' \
'https://htmlpdfapi.com/api/v1/assets'

Assets UPDATE

Update an existing assets on server

URL	Method	Description
/assets	`PUT`	Update an existing asset

Parametars

Parametar	Default	Values	Description
`file`			File for upload. Accepted types are: js, css, png, jpg, jpeg, gif, ttf, otf, woff

Filename is used as identifier.

Response

Succesful response will return JSON object of uploaded file with status 200. Size is defined in bytes.

Response example

{
  "id": "fb2222fad512753f06000002",
  "name": "my_image.jpg",
  "mime": "image/jpeg",
  "size": 40608
}

Example

curl -X PUT -H 'Authentication:Token <your token>' \
-F 'file=@my_image.jpg' \
'https://htmlpdfapi.com/api/v1/assets'

Assets GET

Download asset from server as file.

URL	Method	Description
/assets/:id	`GET`	Get asset by id

Response

Succesful response will return file with status 200.

Example

curl -H 'Authentication:Token <your token>' \
'https://htmlpdfapi.com/api/v1/assets/<asset id>'

Assets DELETE

Delete asset from server.

URL	Method	Description
/assets/:id	`DELETE`	Delete asset by id

Response

Succesful response will return status 204.

Example

curl -X DELETE -H 'Authentication:Token <your token>' \
'https://htmlpdfapi.com/api/v1/assets/<asset id>'

Error responses

Response	Code
Common
Token missing	`401` Unauthorized
Invalid api token	`401` Unauthorized
User is not activated	`403` Forbidden
Internal server error	`500` Internal server error
PDF
Invalid params url, file or html string is missing	`400` Bad request
Invalid params must pass only one parameter (url, file, html)	`400` Bad request
Invalid params. Please check you params and try again	`400` Bad request
Invalid file. Allowed extensions: html, htm, zip, tgz, tar.gz, tar.bz2	`400` Bad request
Invalid URL. Must start with http or https and be in a valid format. e.g. http://example.com/?foo=bar	`400` Bad request
Invalid format of ID parameter	`400` Bad request
File too big. Maximum HTML file size is 3 MB	`413` Request Entity Too Large
File too big. Maximum compressed file size is 100 MB	`413` Request Entity Too Large
Failed loading page	`502` Bad Gateway
Failed loading page resources. Some of resources have returned 404 error.	`502` Bad Gateway
Failed loading page. Authentication required	`511` Network Authentication Required
Failed loading page. Timeout. Maximum load time of remote resources is 30sec	`504` Gateway Timeout
Invalid compressed file	`400` Bad request
HTML file is missing in your compressed file.	`400` Bad request
Not enough credits.	`402` Payment Required
Group with that name does not exist.	`400` Bad request
Failed generating pdf	`500` Internal server error
Assets
Uploaded file has invalid extension.	`400` Bad request
File with that name already exists.	`409` Conflict
Error occured while uploading file.	`500` Internal server error
Invalid params. File is missing.	`400` Bad request
File not found.	`410` Gone
The file upload would exceed disk quota.	`400` Bad request

Appendix

Page sizes for PDF document

List of available page sizes:

A0
A1
A2
A3
A4
A5
A6
A7
A8
A9

B0
B1
B10
B2
B3
B4
B5
B6
B7
B8
B9

C5E
Comm10E
DLE
Executive
Folio
Ledger
Legal
Letter
Tabloid

Boolean

Booleans can be passed in the following formats.

True: '1', 'true'
False: '0', 'false'

images=1
//or
images=true

Units

Units can be passed in the following measures: mm, cm. If mesurement is not defined mm are assummed.

Variables in header and footer

Variable	Description
`{{page}}`	Current page
`{{pages}}`	Total number of pages
`{{webpage}}`	Page url
`{{title}}`	PDF title
`{{section}}`	Section name
`{{subsection}}`	Subsection name
`{{subsubsection}}`	Sub-subsection name

Example

<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <div><strong>{{title}}</strong> - {{page}}/{{pages}}</div>
    <div>Created with htmlpdfapi.com</div>
  </body>
</html>

Header and footer must be in valid HTML with doctype specified.

Generating PDF from compressed files (zip, tar.gz, tar.bz2)

When generating PDF from compressed files we look for the first .html or .htm file in package sorted by alphabet. Other HTML files are not used.

Callback parameter

callback is a string parameter that contains URL. HTML PDF API service will use this URL to send POST request with PDF file. This is the sequence of calls between your application and HTML PDF service:

Layer	Description
Your app	sends a `POST` request `https://htmlpdfapi.com/api/v1/` with `callback` parameter (e.g. `http://yourapplication.com/receive_pdf`) to HTML PDF API.
HTML PDF API	receive request and immediately sends response with code `200` and `status` Processing to Your app.
Your app	can continue to work without blocking.
HTML PDF API	in the meantime service creates PDF and sends POST request on `callback` URL with `file` parameter that contains PDF file to Your app.
Your app	receive `POST` request with PDF file.

The name of file in POST body is file.

This site uses cookies for better user experience. To use HTML PDF API, you must agree to our Privacy policy, including Cookie policy.