API Documentation
Have a question? Contact Us.
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 an http response with Status 200 and JSON info in the 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 | |
html / create | URL / HTML | HTML |
Parameters
You must provide page_url or html parameter. All others parameters are optional.
Parameters | 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 the "pdf/create" method and also work for the "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 occurred. 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 the error details and contain the 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
APIDocsPage.v2.HTML_input
# 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 a limit of 60 requests per minute. If you exceed this limit, you will get a 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 with page_url parameter
# 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