API Documentation (v1, legacy)

All requests go over HTTPS to https://api.printfriendly.com and use HTTP Basic authentication: the API key is the username, and no password is needed. Your key is on your API key page.

The other ways to send a key (the api_key query parameter or body field, Authorization: Bearer, and X-API-Key) work on v1 as well, and are described in the v2 authentication section. On v1 the choice never changes the reply.

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

There is no plain-text endpoint on v1; use /v2/text/create. POST is the usual choice, and GET works as well.

A successful v1 request always answers 302 Found, whichever input you sent (a page_url or html) and whichever endpoint you called. The Location header is the file's address, and the body repeats it:

HTTP/1.1 302 Found
Location: https://storage.printfriendly.com/data-production/pdf_1531957353_e94df5Letter.pdf

{"success":"Redirect to https://storage.printfriendly.com/data-production/pdf_1531957353_e94df5Letter.pdf"}

Some HTTP clients follow the redirect on their own and hand you the file (curl does so only with -L). To get just the address, read the Location header with redirect-following turned off.

Send page_url or html. Everything else is optional. These are the same parameters as v2, except output_type, which v1 ignores.

A failed request returns a JSON body. Every failure carries error.code, a stable snake_case name, and error.retryable, which is true when sending the same request again can succeed. They sit alongside the fields older integrations already read, which have not changed. Branch on the code and the flag, not on the English text, which can be reworded.

Fields

HTTP status codes

Error codes

Internal details such as fetch-error or high-load are not part of the contract. They are folded into the codes above, and the English sentence that goes with them is unchanged.

Examples

A missing parameter (400):

{
  "error": {
    "type": "parameters-validation",
    "errors": { "base": ["You must provide a page_url or html parameter"] },
    "message": "You must provide a page_url or html parameter",
    "code": "invalid_parameters",
    "retryable": false
  }
}

A page we could not load (422):

{
  "status": "failed",
  "message": "Print technology timed-out while trying to connect to this page",
  "error": {
    "code": "fetch_failed",
    "message": "Print technology timed-out while trying to connect to this page",
    "retryable": true
  }
}

The free plan used up for the month (402). A paid plan stopped by its overage setting answers the same way, with its own message and a link to the API key page:

{
  "status": "failed",
  "message": "Your free plan includes 100 documents a month. Upgrade for more.",
  "error": {
    "code": "quota_exceeded",
    "message": "Your free plan includes 100 documents a month. Upgrade for more.",
    "upgrade_url": "https://www.printfriendly.com/api#pricing",
    "retryable": false
  }
}

Too many requests this minute (429):

HTTP/1.1 429 Too Many Requests
Retry-After: 23

{
  "status": "failed",
  "message": "Too many requests. This key allows 10 requests per minute. Retry in 23 seconds.",
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. This key allows 10 requests per minute. Retry in 23 seconds.",
    "retryable": true,
    "retry_after_seconds": 23
  }
}