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

# Przegląd API Paperjoy

> Adres bazowy, uwierzytelnianie, konwencje i wszystkie publiczne endpointy API Paperjoy.

API Paperjoy to API JSON przez HTTPS do tworzenia i śledzenia odręcznych pocztówek. Zaczynasz? Przejdź do [Szybkiego startu](https://docs.paperjoy.co/getting-started/quickstart.md).

## Adres bazowy

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

## Uwierzytelnianie

W każdym żądaniu wyślij [klucz API](https://docs.paperjoy.co/getting-started/authentication.md) jako token bearer:

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

Klucz `pj_test_` wykonuje każde żądanie w [trybie testowym](https://docs.paperjoy.co/getting-started/test-mode.md), a klucz `pj_live_` w trybie live. Ścieżki i body są identyczne w obu trybach.

## Endpointy

| Metoda | Ścieżka | Działanie |
| - | - | - |
| `GET` | `/api/user` | Twoje konto i saldo kredytów. |
| `POST` | `/api/postcards` | Utworzenie pocztówki. |
| `POST` | `/api/postcards/preview` | Obraz PNG kartki. |
| `GET` | `/api/postcards` | Lista Twoich pocztówek, od najnowszych, po jednej stronie naraz. |
| `GET` | `/api/postcards/{id}` | Jedna pocztówka. |
| `GET` | `/api/signatures` | Lista Twoich własnych podpisów. |
| `GET` | `/api/signatures/{id}` | Jeden podpis. |
| `DELETE` | `/api/signatures/{id}` | Usunięcie podpisu. |

Szczegóły każdego endpointu znajdziesz w sekcji **Endpointy API** w menu.

## Konwencje

* **Nagłówki.** W każdym żądaniu wysyłaj `Accept: application/json`, a z body `Content-Type: application/json`. Endpoint podglądu zwraca `image/png`.
* **Koperta odpowiedzi.** Poprawne odpowiedzi JSON zawierają wynik w polu `data`.
* **ID.** Identyfikatory to nieprzezroczyste ciągi z prefiksem: `pc_` dla pocztówek, `sig_` dla podpisów, `user_` dla użytkowników. Przechowuj je jako tekst.
* **Daty.** ISO 8601 z przesunięciem UTC, np. `2026-10-17T14:31:48+00:00`. Pola dotyczące zdarzeń, które jeszcze nie nastąpiły, mają wartość `null`.
* **Idempotency.** `POST /api/postcards` wymaga nagłówka `Idempotency-Key`. Zobacz [Bezpieczne ponowienia](https://docs.paperjoy.co/postcards/create.md#bezpieczne-ponowienia).
* **Błędy.** Body JSON z `message` oraz `errors` przy błędach walidacji. Komunikaty są po angielsku. Zobacz [Błędy i limity](https://docs.paperjoy.co/reference/errors-and-rate-limits.md).
* **Zgodność.** Możemy dodawać pola i wartości statusów. Ignoruj pola, których nie używasz, i obsługuj nieznane statusy bez błędu.


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