> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperjoy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Paperjoy API overview

> Base URL, authentication, conventions, and every public endpoint of the Paperjoy API.

The Paperjoy API is a JSON over HTTPS API for creating and tracking handwritten postcards. New to it? Start with the [Quickstart](https://docs.paperjoy.co/en/getting-started/quickstart.md).

## Base URL

```text theme={null}
https://paperjoy.co/api
```

## Authentication

Send an [API key](https://docs.paperjoy.co/en/getting-started/authentication.md) as a bearer token on every request:

```text theme={null}
Authorization: Bearer pj_live_...
```

A `pj_test_` key runs every request in [test mode](https://docs.paperjoy.co/en/getting-started/test-mode.md); a `pj_live_` key runs it in live mode. Paths and bodies are identical in both.

## Endpoints

| Method | Path | Does |
| - | - | - |
| `GET` | `/api/user` | Your account and credit balance. |
| `POST` | `/api/postcards` | Create a postcard. |
| `POST` | `/api/postcards/preview` | Render the card as a PNG. |
| `GET` | `/api/postcards` | List your postcards, newest first, one page at a time. |
| `GET` | `/api/postcards/{id}` | Retrieve one postcard. |
| `GET` | `/api/signatures` | List your custom signatures. |
| `GET` | `/api/signatures/{id}` | Retrieve one signature. |
| `DELETE` | `/api/signatures/{id}` | Delete a signature. |

Each endpoint has its own page with the full schema under **Endpoints** in the sidebar.

## Conventions

* **Headers.** Send `Accept: application/json` on every request and `Content-Type: application/json` with a body. The preview endpoint returns `image/png`.
* **Envelope.** Successful JSON responses wrap the result in `data`.
* **IDs.** IDs are opaque strings with a prefix: `pc_` for postcards, `sig_` for signatures, `user_` for users. Store them as strings.
* **Timestamps.** ISO 8601 with a UTC offset, such as `2026-10-17T14:31:48+00:00`. Fields that haven't happened yet are `null`.
* **Idempotency.** `POST /api/postcards` requires an `Idempotency-Key` header. See [Retry safely](https://docs.paperjoy.co/en/postcards/create.md#retry-safely).
* **Errors.** A JSON body with `message`, plus `errors` for validation failures. See [Errors and rate limits](https://docs.paperjoy.co/en/reference/errors-and-rate-limits.md).
* **Compatibility.** We may add fields and status values. Ignore fields you don't use and handle unknown statuses gracefully.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.