# Introduction (/docs/api)



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 [#base-url]

All API requests are made to:

```text
https://api.paperful.io/v1
```

For example:

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

## Authentication [#authentication]

Paperful uses API keys to authenticate requests.

Send your API key using the Authorization header:

```http
Authorization: Bearer YOUR_API_KEY
```

You can create and manage API keys from the [Console](https://console.paperful.io/keys). See [API Keys](/docs/platform/api-keys) for best practices.

<Callout type="warn">
   Keep your API keys secure. Never expose them in client-side code or commit them to source control.
</Callout>

## Requests [#requests]

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

Some endpoints, such as [document uploads](/docs/api/papers/upload), accept binary file data. Requests are [rate limited](/docs/platform/limits#api-requests) per workspace.

```bash
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 [#responses]

Successful requests return standard HTTP status codes and JSON responses.

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

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

## Pagination [#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.

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

## Versioning [#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 [#sdks]

You can use the REST API directly or interact with Paperful through one of our [SDKs](/docs/sdks).
