Quickstart

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 able to upload files to it. To do this you'll create an AWS user and generate credentials which are used to upload to S3.

Creating an AWS user

First, navigate to the "IAM" service in the AWS console.

Next, navigate to "Users". You'll see a screen looking something like this:

Next, click "Add user" and choose a suitable user name. Make sure that "Programmatic access" is enabled:

Click through to "Permissions" and select the option to attach the "AmazonS3FullAccess" policy directly to the user:

Click through the following steps, and finally create the user.

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.

After creating the user, you'll be able to download the "Access key ID" and "Secret access key". Make sure to save these as you won't be able to access the secret key again (although you can easily generate a new set of credentials).

Generating your first PDF

To confirm the user is properly set up, let’s go to Paperplane and create a new "Destination".

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

Under “Destination”, click “New Destination”. Enter the AWS credentials, bucket name and bucket region:

Finally, click "Create API Key" to add an API key to the destination:

Choose an appropriate name to identify the API key:

Your API key is now ready to use!

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

$ 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”.