API Instructions

Have a question? Email the boss.

All API requests must be made over HTTPS and need api_key as a URL query parameter

Example

curl https://api.printfriendly.com/v2/pdf/create?api_key=YOUR_API_KEY \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  -d page_url=https://en.wikipedia.org/wiki/Eclipse

In case of success you will get http response with Status 200 and JSON info in response body.

{"status":"success","file_url":"https://api.printfriendly.com/downloads/pdf_1531957353_e94df5Letter.pdf"}

API Version

Current version of API is 2.0.
Major API version must be provided in URL as ‘v’ and number, ie. v1, v2, v3.

Example

https://api.printfriendly.com/v2/pdf/create
https://api.printfriendly.com/v2/html/create

API Methods

Method	Input	Output
pdf/create	URL / HTML	PDF
html/create	URL / HTML	HTML

Parameters:

You must provide page_url or html parameter. All others parameters are optional.

Parameter	Value
page_url	URL of target page
html	HTML content of target page
output_type	Set it to "attachment" to receive the PDF file as the output instead of JSON
css_url	URL for Custom CSS file
header_image_url	URL for Custom Header image
header_text	Text String

All examples below are provided for "pdf/create" method but also work for "html/create" method.

Example with page_url parameter

curl https://api.printfriendly.com/v2/pdf/create?api_key=YOUR_API_KEY \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  -d page_url=https://test.test \
  -d css_url=https://my-site.com/pdf_style.css \
  -d header_text='My Custom Header'

HTML input

curl https://api.printfriendly.com/v2/pdf/create?api_key=YOUR_API_KEY \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  -d html='<html><body><h1>Title</h1><p>Text text text text text text text text text</p></body></html>'

Errors

Printfriendly uses conventional Status codes and JSON response to provide error details.

Status Codes

Status	Description
200 OK	Everything works fine
400 Bad Request	Error has occured. See details in JSON
401 Unauthorized	Authentication failed. No valid API key provided
404 Not Found	API method/route not found
429 Too Many Requests	Too many requests

All not success (not Status 200) responses have JSON body with error details which contains error type and message.

Error types

Type	Description
parameters-validation	Parameters validation failed
banned-domain	This domain is temporary banned
failed-parsed	Can’t parse page. We can’t determine content of this page
fetch-error	Can’t fetch page. Check that URL is accessible and try again
high-load	We are under high load. Please try again later
invalid-file-ext	Only webpages are supported. It’s a PDF/TXT file or Image (JPG, PNG, GIF)
large-page	Target page is over 2Mb. Big pages are not supported
security-platform	Security platform blocks us from fetching this page
timeout	Timeout exceeded. Engine can’t process the page during 30 secs. Please try again later
catch-all	Unexpected error. Please try again later

Example

curl https://api.printfriendly.com/v2/pdf/create?api_key=YOUR_API_KEY \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
-d page_url=https://test.test

# HTTP RESPONSE

# HEADERS (some of headers were ommited)
Content-Type: application/json; charset=utf-8
Status: 400 Bad Request

# BODY (JSON)
{"status":"failed","message":"Print technology unable to download or parse content"}

Requests Rate Limiting

The API has 60 requests per minute limit. If your requests limit exceeded you will get response with Status: 429 Too Many Requests.

Header	Description
X-RateLimit-Limit	Total requests limit for current period
X-RateLimit-Remaining	Remaining request for current period
X-RateLimit-Reset	Amount of seconds till the end of current period

Example

# HEADERS (some of headers were ommited)

Status: 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 20

# BODY (JSON)
Empty

All API requests must be made over HTTPS and use HTTP Basic Auth with the following credentials:

Username: API KEY
Password: Not needed

Example

curl https://api.printfriendly.com/v1/pdfs/create \
  -u your_api_key: \
  -d page_url=https://en.wikipedia.org/wiki/Eclipse

Flag	Description
-u	pass basic auth credentials, a colon after API key prevents cURL from asking for a password
-d	send data in POST request

In case of success you will get http response with Status 302 (Redirect) and JSON info in response body.

# HTTP RESPONSE

# HEADERS (some of headers are ommited)
Content-Type: application/json; charset=utf-8
Status: 302 Found
Location: https://v.printfriendly.com/system/pdfs/pdf_1480936999_755625A4.pdf

# BODY
{"success":"Redirect to https://v.printfriendly.com/system/pdfs/pdf_1480947535_6e7ecaA4.pdf"}

API Version

Current version of API is 1.0.
Major API version must be provided in URL as ‘v’ and number, ie. v1, v2, v3.

Example

https://api.printfriendly.com/v1/pdf/create
https://api.printfriendly.com/v1/html/create

API Methods

Method	Input	Output
pdf/create	URL / HTML	PDF
html/create	URL / HTML	HTML

Parameters:

You must provide page_url or html parameter. All others parameters are optional.

Parameter	Value
page_url	URL of target page
html	HTML content of target page
css_url	URL for Custom CSS file
header_image_url	URL for Custom Header image
header_text	Text String

All examples below are provided for "pdf/create" method but also work for "html/create" method.

Example with page_url parameter

curl https://api.printfriendly.com/v1/pdfs/create \
  -u your_api_key: \
  -d page_url=https://test.test \
  -d css_url=https://my-site.com/pdf_style.css \
  -d header_text='My Custom Header'

In case of success you will get http response with Status 302 (Redirect) and JSON info in response body.

Example with html parameter

curl https://api.printfriendly.com/v1/pdfs/create \
  -u your_api_key: \
  -d html='<html><body><h1>Title</h1><p>Text text text text text text text text text</p></body></html>'

In case of success you will get http response with Status 200 and PDF/HTML content in response body.

Errors

Printfriendly uses conventional Status codes and JSON response to provide error details.

Status Codes

Status	Description
200 OK	Everything works fine
400 Bad Request	Error has occured. See details in JSON
401 Unauthorized	Authentication failed. No valid API key provided
404 Not Found	API method/route not found
429 Too Many Requests	Too many requests

All not success (not Status: 302 OK) responses have JSON body with error details which contains error type and message.

Error types

Type	Description
parameters-validation	Parameters validation failed
banned-domain	This domain is temporary banned
failed-parse	Can’t parse page. We can’t determine content of this page
fetch-error	Can’t fetch page. Check that URL is accessible and try again
high-load	We are under high load. Please try again later
invalid-file-ext	Only webpages are supported. It’s a PDF/TXT file or Image (JPG, PNG, GIF)
large-page	Target page is over 2Mb. Big pages are not supported
security-platform	Security platform blocks us from fetching this page
timeout	Timeout exceeded. Engine can’t process the page during 30 secs. Please try again later
catch-all	Unexpected error. Please try again later

Example

curl https://api.printfriendly.com/v1/pdfs/create \
  -u your_api_key: \
  -d page_url=https://test.test

# HTTP RESPONSE

# HEADERS (some of headers were ommited)
Content-Type: application/json; charset=utf-8
Status: 400 Bad Request

# BODY (JSON)
{"error":{"type":"failed","message":"Print technology unable to download or parse content"}}

Requests Rate Limiting

The API has 60 requests per minute limit. If your requests limit exceeded you will get response with Status: 429 Too Many Requests.

Header	Description
X-RateLimit-Limit	Total requests limit for current period
X-RateLimit-Remaining	Remaining request for current period
X-RateLimit-Reset	Amount of seconds till the end of current period

Example

# HEADERS (some of headers were ommited)

Status: 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 20

# BODY (JSON)
Empty