Quickstart

Learn how to generate your first PDF document.

To get started you’ll need an Amazon Web Services account so that PDFs can be uploaded to S3, Amazon’s cloud storage service. If you don’t already have an account, sign up here. New accounts get 5GB of storage free for a year.

Paperplane stores all your generated PDFs on your own S3 cloud storage bucket. If you don’t know how to create an S3 bucket, follow the instructions under “Setting up an S3 bucket” before coming back here.

Now that you have an S3 bucket created, Paperplane needs to be given permission to upload files to it. In the S3 section of the AWS console, click on your bucket name, then go to the “Permissions” tab. Click “Bucket Policy” then paste in the bucket policy from the “Setting up an S3 bucket” article.

This quick video walks through the process of adding the policy to your bucket.

Setting the bucket policy using the AWS web console

It’s also possible to use the AWS command line interface to set the policy using your terminal. If you prefer to do this, you can refer to the instructions under “Setting up an S3 bucket”.

To confirm the bucket is all set up, let’s go to Paperplane and create a new API key.

Go to dash.paperplane.app and sign in to your account.

  • Under “API keys”, click “New API key”.

  • Give the key a name (for example “test” or “production”) and enter the name of the S3 bucket that you just set up.

  • You’ll also need to choose the AWS region where the bucket is located.

When you hit “Create API key”, the bucket permissions are validated. If the API key was created, everything is ready to go!

Now you’re ready to create a PDF. Here’s an example of creating a new PDF job using the curl command line utility:

Replace myapikey with the API key you just generated.

$ 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"
}

The URL you supply must be publicly accessible so that Paperplane can load it. However, you can use an unguessable key such as a UUID in the URL to ensure data remains private. For more details, check out the guide on “Securing access to HTML documents”.

When you create a new job, the API returns the job’s ID and current status, which will initially be queued. Soon afterwards (normally within 30 seconds) Paperplane will start processing the job by visiting the URL, saving a PDF and uploading it to your S3 bucket. You can check the status of the job by using its ID. 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": "delivered",
"done": true,
"object": "job"
}

When the PDF has been delivered to S3, the job status will update to delivered. If the job fails for any reason, that status will update to either creation_failed or delivery_failed. More details on the job statuses can be found in the API reference.

That’s it - you’ve created your first PDF! For details on all the configuration options available, check out “Customizing the PDF”.