API Documentation
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://storage.printfriendly.com/data-production/pdf_1480936999_755625A4.pdf
# BODY
{"success":"Redirect to https://storage.printfriendly.com/data-production/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.
https://api.printfriendly.com/v2/pdf/create
https://api.printfriendly.com/v2/html/createAPI 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.testHTML 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"}Quotas
Each API plan has a monthly quota of PDF/HTML/text generations. Usage resets at the start of every billing period. When you exceed your quota, subsequent requests return 401 Unauthorized with API Limit Exceeded.