API Documentation
Have a question? Contact Us.
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 an http response with Status 302 (Redirect) and the JSON info will be in the 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/v2/pdf/create
https://api.printfriendly.com/v2/html/create
API Methods
Method | Input | Output |
|---|---|---|
pdf / create | URL / HTML | HTML |
html / create | URL / 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 |
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/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 an http response with Status 302 (Redirect) and the JSON info will be in the response body.
Example with html parameters
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 occurred. See details in JSON. |
401 Unauthorized | 401 Unauthorized |
404 Not Found | 404 Not Found |
429 Too Many Requests | 429 Too Many Requests |
All not success (not Status 302 OK) responses have JSON body with the error details, which will include 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 | Parameters validation failed. |
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
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