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.

[Response body will contain PDF data]

{"message":"invalid API key"}

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.

{
  "id": "fe748521-5d8f-43d8-9093-7970d2d032d7",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "queued",
  "done": false,
  "object": "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.

{
  "id": "fe748521-5d8f-43d8-9093-7970d2d032d7",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "queued",
  "done": false,
  "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.