Dokumentacja API ProofSnap

API ProofSnap otwiera dowolny adres URL w przeglądarce na serwerach ProofSnap i zwraca zapieczętowany pakiet dowodowy: zrzut ekranu, kod HTML, metadane, raport dowodowy w formacie PDF oraz manifest ze skrótami SHA-256, podpisany kluczem RSA-4096 i przesłany do zakotwiczenia w Bitcoinie przez OpenTimestamps. Bazowy URL: https://api.getproofsnap.com/v1. Uwierzytelnianie: klucz API przekazywany jako token Bearer. Zaktualizowano 23 października 2026 r.

Poniższe przykłady pobierają bazowy URL ze zmiennej środowiskowej: export PROOFSNAP_API_BASE=https://api.getproofsnap.com/v1

Pierwsze kroki

1
Utwórz klucz API

Zaloguj się do panelu, otwórz „Dla deweloperów”, a potem „Klucze API” i kliknij „+ Nowy klucz”. Klucz jest wyświetlany tylko raz, więc od razu zapisz go w bezpiecznym miejscu. Klucze zaczynają się od ps_live_ lub ps_test_. Otwierasz panel po raz pierwszy? Przewodnik „Pierwsze kroki w panelu ProofSnap” przeprowadzi Cię przez rejestrację, wybór planu i pierwsze przechwycenie. Kolejne instrukcje znajdziesz w przewodnikach po panelu.

Wykonaj pierwsze przechwycenie

Przekaż klucz jako token Bearer. Wywołanie od razu zwraca kod 202 z polami capture_id i status: "processing".

curl -X POST "$PROOFSNAP_API_BASE/captures" \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

3
Odbierz wynik

Odpytuj GET /captures/{capture_id}, aż status przyjmie wartość completed lub failed. Ukończone przechwycenie zawiera package_url (wstępnie podpisany link do pliku ZIP, ważny do 24 godzin) oraz manifest_hash. Nowy link otrzymasz, pobierając przechwycenie ponownie. Zamiast odpytywania możesz w options.webhook_url podać endpoint HTTPS, na który trafi podpisane (HMAC-SHA256) zdarzenie capture.completed lub capture.failed.
```
curl "$PROOFSNAP_API_BASE/captures/cap_..." \
  -H "Authorization: Bearer ps_live_..."
```
4
Zweryfikuj pakiet

POST /captures/{capture_id}/verify ponownie porównuje każdy zadeklarowany skrót SHA-256 z przechowywanymi plikami, sprawdza podpis RSA-4096 manifestu i zwraca match, modified lub invalid. Każdy może też uruchomić w trybie offline skrypty z folderu verification/ w pakiecie albo wyszukać skrót SHA-256 pliku manifest.json w publicznym rejestrze wydanych pakietów przez GET /ledger/{hash}. Żaden z tych dwóch sposobów nie wymaga klucza API.
```
curl -X POST "$PROOFSNAP_API_BASE/captures/cap_.../verify" \
  -H "Authorization: Bearer ps_live_..."
```

Uwierzytelnianie

Klucz API (API key) wysyłaj w nagłówku Authorization: Bearer ps_live_.... Klucze zaczynają się od ps_live_ lub ps_test_. Klucz produkcyjny tworzy płatne przechwycenia, a klucz testowy pełne pakiety ze znakiem wodnym, za które nie płacisz. Jeśli do konta nie podpięto rozliczeń, klucz produkcyjny działa jak testowy. Gdy brakuje klucza, API zwraca 401 MISSING_API_KEY, a przy nieznanym lub unieważnionym kluczu 401 INVALID_API_KEY. Klucze planu Website Archive są tylko do odczytu (403 PLAN_API_READ_ONLY). Trzy ścieżki nie wymagają klucza: GET /health, GET /ledger/{hash} i GET /matter-verify.

Nowe konto działa początkowo w trybie testowym (sandbox) z 50 bezpłatnymi przechwyceniami testowymi. Użycie w trybie testowym jest ograniczone do 200 jednostek dziennie na konto (doba liczona według UTC, 429 TEST_MODE_DAILY_LIMIT), pakiety mają znak wodny „TEST - NOT FOR LEGAL USE” (w polskiej wersji PDF „TEST - NIE DO UŻYTKU PRAWNEGO”), a include_eidas wymaga klucza produkcyjnego (403 EIDAS_REQUIRES_LIVE_KEY).

Webhooki

Podaj options.webhook_url w pojedynczym żądaniu albo utwórz subskrypcje webhooków dla całego konta przez POST /webhook-subscriptions. Webhooki są wysyłane w formacie Standard Webhooks z nagłówkami webhook-id, webhook-timestamp i webhook-signature (v1,, a po nim HMAC-SHA256 obliczony z identyfikatora, znacznika czasu i treści przy użyciu sekretu whsec_). Typy zdarzeń: capture.completed, capture.failed, capture.anchor_confirmed, certify.completed, certify.failed, redaction.completed, redaction.failed, monitor.change_detected i schedule.paused. Zdarzenia capture.anchor_confirmed i schedule.paused trafiają tylko do subskrypcji obejmujących całe konto. Każde zdarzenie można też przez 30 dni pobrać z endpointu GET /events. Limit czasu jednej próby dostarczenia wynosi 10 sekund, a nieudane próby są ponawiane po 5 minutach, 30 minutach, 2 godzinach, 8 godzinach i 24 godzinach. Przez 24 godziny po wygenerowaniu nowego sekretu webhooki są podpisywane zarówno starym, jak i nowym sekretem.

Webhooki wysyłane na webhook_url podany w żądaniu są podpisywane sekretem klucza API, którym wysłano to żądanie. Ten sekret podpisu webhooka jest wyświetlany tylko raz, przy tworzeniu klucza w sekcji „Dla deweloperów” w panelu. Subskrypcja ma własny sekret, zwracany tylko raz przy jej utworzeniu. Weryfikuj podpis na podstawie surowej treści żądania, zanim ją sparsujesz. Odrzucaj każdy webhook, którego webhook-timestamp różni się od czasu Twojego serwera o więcej niż 5 minut. Każdy webhook-id przetwarzaj tylko raz. Każda biblioteka Standard Webhooks zrobi to za Ciebie.

Limity żądań i błędy

Płatne żądania (POST /captures, /captures/batch, /compare, /captures/{capture_id}/redact i /certify-hash, a także żądania weryfikacji, blokad prawnych, zadań eksportu i importu) są limitowane dla każdego konta w stałych oknach czasowych po 60 sekund, wspólnych dla wszystkich kluczy API konta i jego sesji w panelu. Żądanie wsadowe lub certyfikacja wielu skrótów zużywa jedną jednostkę na każdy adres URL lub skrót. Jednostki na okno: sandbox 10, Developer 60, Startup 120, Growth 300, Legal Solo 60, Legal Company 120, Website Archive 60, Archive only 30. Odpowiedzi z tych ścieżek zawierają nagłówki RateLimit-Policy i RateLimit oraz starsze nagłówki X-RateLimit-*, a odpowiedź 429 zawiera dodatkowo nagłówek Retry-After.

Przechwycenia produkcyjne wliczają się do miesięcznego limitu planu (402 QUOTA_EXCEEDED), a gdy konto zalega z płatnością za subskrypcję, API odpowiada na jego żądania błędem 402 PAYMENT_REQUIRED. W ramach jednego konta może być jednocześnie przetwarzana tylko ograniczona liczba przechwyceń (429 CONCURRENT_CAPTURE_LIMIT). Jeśli wyślesz nagłówek Idempotency-Key, ponowienie żądania w ciągu 24 godzin zwróci pierwotny wynik z nagłówkiem Idempotent-Replay: true, zamiast utworzyć drugie przechwycenie. Błędy są zwracane jako obiekt JSON z polami error.code, error.message i w razie potrzeby error.details. Kontaktując się z pomocą techniczną, podaj wartość nagłówka odpowiedzi X-Request-ID. Pełna lista kodów znajduje się w dokumentacji poniżej.

Endpointy w skrócie

Przechwycenia: POST /captures, POST /captures/batch (od 2 do 50 adresów URL), GET /captures, GET /captures/hosts, GET /captures/{capture_id}, PATCH i DELETE /captures/{capture_id}, POST /captures/{capture_id}/verify
Zaczernianie, porównywanie i certyfikacja: POST /captures/{capture_id}/redact (zaczernianie), POST /compare, POST /certify-hash (do 100 skrótów)
Automatyzacja: /scheduled-captures (zaplanowane przechwycenia wraz z historią uruchomień /runs), /webhook-subscriptions, GET /webhook-events/{capture_id}, GET /events, GET /captures/events
Funkcje dla prawników: /matters (sprawy: pieczętowanie, eksport, udostępnianie), POST /legal-holds (blokady prawne), /imports, /captures/export-jobs
Konto i ścieżki publiczne: GET /whoami, GET /health, GET /ledger/{hash}, GET /matter-verify

Pełna dokumentacja

Wszystkie endpointy z parametrami, odpowiedziami i schematami, wygenerowane ze specyfikacji OpenAPI 3. Specyfikację pobierzesz jako openapi.json (po angielsku, dla generatorów kodu) lub openapi-pl.json (opisy po polsku). Aby wypróbować dowolny endpoint bez pisania kodu, utwórz fork kolekcji ProofSnap API w Postmanie. Nie udostępniamy oficjalnego SDK: wygeneruj klienta dowolnym generatorem OpenAPI 3, a webhooki weryfikuj biblioteką Standard Webhooks.