API reference

ND
Last updated 3 months ago

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

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.

post
Create job

https://api.paperplane.app
/jobs
Request
Response
Form Data Parameters
url
required
string
The URL to fetch and convert to PDF.
200: OK

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
Show job

https://api.paperplane.app
/jobs/:id
Request
Response
Path Parameters
id
required
string
The job ID provided when the job was created.
200: OK
{"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:

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.