API reference

Full details on all API endpoints, request parameters and response formats.

Authentication
All API requests require authentication, which is done using HTTP basic authentication. Send your API key as the username. The password can be left blank.
Many of the examples in these docs use the curl command line program. To authenticate with curl, use the -u flag. Adding a colon after the API key will prevent curl from asking for a password. For example:
$ curl -u myapikey: https://api.paperplane.app/jobs/my-job-id
Introduction to PDF downloads and jobs
The Paperplane API allows you to generate a PDF and download it directly, or to start a new PDF job and have the PDF created and uploaded to your S3 bucket asynchronously.
To download PDFs directly, use the Download PDF endpoint. To generate a PDF job and have the PDF created asynchronously, use the Create Job endpoint. The parameters for both of these endpoints are the same. The only required parameter is url, which specifies the URL to fetch and convert to PDF. You can view all other options on the "Customizing the PDF" guide.
Request format
You can provide parameters to API endpoints either by using HTTP form data, or by using JSON.
Here's an example of a request that uses curl to provide parameters as form data:
$ curl -u myapikey: https://api.paperplane.app/jobs \
  -d url="https://en.wikipedia.org/wiki/Airplane" \
  -d page_size="A4"
And here's an example of a request body in JSON format.
{
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "page_size": "A4"
}
Remember to set the Content-Type if your HTTP client doesn't do this automatically. For form data this should be application/x-www-form-urlencoded, and for JSON it should be application/json.
You can find example code for many popular languages on the Code Samples page.
post
https://download.paperplane.app
/
Download PDF
Here's an example using curl:
$ curl -u myapikey: https://download.paperplane.app/ -d url="https://en.wikipedia.org/wiki/Airplane" -o example.pdf
This command will download the PDF to the file test.pdf.
post
https://api.paperplane.app
/jobs
Create Job
Here's an example using curl:
$ curl -u myapikey: https://api.paperplane.app/jobs -d url="https://en.wikipedia.org/wiki/Airplane"
​
{
  "id": "fe748521-5d8f-43d8-9093-7970d2d032d7",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "queued",
  "done": false,
  "object": "job"
}
To configure the PDF output, see “Customizing the PDF”. It describes the optional parameters you can provide when creating a new job.
You can create as many jobs as you like at once. Jobs will be queued and processed in the order you create them.
Checking the status of a job
You can check whether the job has completed, failed or is in progress by making a GET request to the jobs endpoint, specifying the ID of the job you want to check.
get
https://api.paperplane.app
/jobs/:id
Show job
Here's an example using curl:
$ curl -u myapikey: https://api.paperplane.app/jobs/fe748521-5d8f-43d8-9093-7970d2d032d7
​
{
  "id": "fe748521-5d8f-43d8-9093-7970d2d032d7",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "queued",
  "done": false,
  "object": "job"
}
Job statuses
These are all the possible job status values:
Status
Description
queued
The job is queued and is waiting to be processed.
started
The job is currently being processed.
delivered
The job has completed successfully and been uploaded to S3.
creation_failed
The job failed whilst trying to create the PDF. For example, this could occur if the URL you provide is not valid or can’t be reached.
delivery_failed
The job failed whilst trying to upload the PDF to S3. For example, this could occur if the S3 bucket permissions have been changed or the bucket was deleted.
Retrying jobs
If a job fails and you’d like to retry it, just create a new job with the same URL. The first three failed jobs for each URL you submit do not count towards your usage. However any additional failed jobs after the third attempt will count against your usage.
Rate limiting
There is a rate limit of 600 requests / minute in place on the jobs endpoint which is in place to make sure all customers receive a good quality of service. If you do hit the rate limit, you’ll receive a response with a 429 status. You can use Retry-After header that’s set in this response to determine how many seconds to wait making the next request.

Destinations & API keys

Customizing the PDF

Last modified 3yr ago

Status	Description
`queued`	The job is queued and is waiting to be processed.
`started`	The job is currently being processed.
`delivered`	The job has completed successfully and been uploaded to S3.
`creation_failed`	The job failed whilst trying to create the PDF. For example, this could occur if the URL you provide is not valid or can’t be reached.
`delivery_failed`	The job failed whilst trying to upload the PDF to S3. For example, this could occur if the S3 bucket permissions have been changed or the bucket was deleted.