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

Jobs

A job in Paperplane is an instruction to convert a web page to PDF. The jobs endpoint allows you to create jobs and monitor their status.

Creating a new job

Make a POST request to the jobs endpoint to create a new job. You must set a url parameter - this is the URL that will be loaded and converted to PDF.

​

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.

{"id":"25688a9a-f59a-49dc-a165-2ec6f47e3434","url":"https://en.wikipedia.org/wiki/Airplane","status":"delivered", ”done”: true, “object”:”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:

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.