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.

Download PDF

POST https://download.paperplane.app/

This endpoint generates a PDF and allows you to download it directly in the response. This endpoint is synchronous and will block until the PDF has successfully been generated or has failed to generate. Typical PDF generation times are around 5 to 15 seconds. When using the download endpoint, completed PDFs will still be uploaded to your S3 bucket for your future reference. If the server returns a 200 OK HTTP status, the body will contain the PDF data. The x-paperplane-job-id header in the response will provide the job ID used to generate the PDF. If an error is encountered trying to create the PDF, a non-200 response will be returned with a JSON formatted body which will provide an error message. To configure the PDF output, see “Customizing the PDF”. It describes the optional parameters you can provide to this endpoint.

Path Parameters

Name	Type	Description
url	string	The URL to fetch and convert to PDF.

200

[Response body will contain PDF data]

401

{"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.

Create Job

POST https://api.paperplane.app/jobs

This endpoint creates a PDF job. The API will return a response with the job details immediately, and the PDF will be generated asynchronously in the background. Once the PDF is generated, it will be uploaded to your S3 bucket. It's possible to set up webhook notifications that are delivered when the PDF job is completed - see the Webhooks page for details on this.

Request Body

Name	Type	Description
url	string	The URL to fetch and convert to PDF.

200

{
  "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.

Show job

GET https://api.paperplane.app/jobs/:id

Path Parameters

Name	Type	Description
id	string	The job ID provided when the job was created.

200

{
  "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:

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.