API Reference

The Paperful API gives you programmatic access to documents, their content, structure, search, and processing capabilities.

Use the API to upload and process documents, retrieve structured content, search across your workspace, and integrate Paperful into your applications and AI workflows.

Base URL

All API requests are made to:

https://api.paperful.io/v1

For example:

curl https://api.paperful.io/v1/papers \
  -H "Authorization: Bearer $PAPERFUL_API_KEY"

Authentication

Paperful uses API keys to authenticate requests.

Send your API key using the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can create and manage API keys from the Console.

Keep your API keys secure. Never expose them in client-side code or commit them to source control.

Requests

The API follows standard HTTP conventions and uses JSON for request and response bodies unless otherwise specified.

Some endpoints, such as document uploads, accept binary file data.

curl -X POST https://api.paperful.io/v1/papers \
  -H "Authorization: Bearer $PAPERFUL_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf

Responses

Successful requests return standard HTTP status codes and JSON responses.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "fileName": "document.pdf",
  "status": "ready",
  "pages": 12
}

When a request fails, Paperful returns a structured error that can be handled programmatically.

{
  "error": {
    "code": "papers.not_found",
    "message": "The requested paper could not be found."
  }
}

Pagination

Endpoints that return collections may use pagination.

Pagination information is included alongside the returned resources, allowing you to request additional results without loading an entire collection at once.

{
  "total": 0,
  "cursor": {
    "previous": "",
    "next": ""
  },
  "items": []
}

Versioning

The current API version is v1.

The API version is included directly in the request URL.

We aim to make backwards-compatible improvements whenever possible. Breaking changes will be introduced through a new API version.

SDKs

You can use the REST API directly or interact with Paperful through one of our SDKs.

Paperfuldocs