Dokumentacja API

API Prewalk jest częścią planu Korporacyjnego. Za pomocą klucza API Twoje własne oprogramowanie może tworzyć spacery, przesyłać sceny, publikować, odczytywać projekty i statystyki oraz otrzymywać podpisany webhook na każdym etapie przetwarzania. Ta strona to dokumentacja referencyjna; studio i publiczny odtwarzacz działają tak jak dotąd.

Bazowy adres URL i konwencje

• Bazowy adres URL: https://prewalk.co. Nie używaj app.prewalk.co: ten adres przekierowuje (308), a większość klientów HTTP pomija nagłówek Authorization przy przekierowaniu na inny host.
• Format: JSON na wejściu i wyjściu (Content-Type: application/json), z wyjątkiem przesyłania scen, w którym obraz jest wysyłany jako surowa treść żądania.
• Identyfikatory składają się z 12 małych liter i cyfr, np. teeg8crtm0u0. Daty są w formacie ISO 8601 w strefie UTC.
• Błędy zawsze wyglądają tak samo: status HTTP i {"error": {"code": "…", "message": "…"}}; błędy walidacji zawierają dodatkowo field. Kody są wymienione na końcu tej strony.
• Limit żądań: 600 żądań na minutę na klucz. Po jego przekroczeniu otrzymasz 429 z nagłówkiem Retry-After (w sekundach).

Uwierzytelnianie

Utwórz klucz w sekcji Ustawienia → API (właściciel konta lub administrator, plan Korporacyjny). Klucz należy do konta, można go ograniczyć do jednego profilu marki i ma maksymalnie trzy zakresy: read, write i stats. Pełny klucz jest wyświetlany tylko raz; na liście widać wyłącznie jego prefiks. Na jedno konto przypada maksymalnie 20 kluczy; unieważniony klucz przestaje działać natychmiast.

Authorization: Bearer pw_…

Klucz działa w imieniu jednego konta. GET /api/me opisuje, co widzi klucz: konto i limity jego planu, profile tego konta, profil, w imieniu którego działa klucz (actor), oraz sam klucz z jego zakresami. Nigdy nie zwraca adresu e-mail właściciela klucza ani jego innych kont.

Endpointy

Metoda i ścieżka	Zakres	Działanie
GET /api/me	read	Konto, profile i zakresy klucza
GET /api/tours	read	Lista spacerów konta (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}	read	Jeden spacer z jego scenami, punktami przejścia i ustawieniami
GET /api/tours/{id}/events	read	Postęp przetwarzania jako strumień zdarzeń SSE (server-sent events)
POST /api/tours	write	Tworzenie spaceru ({"title": "…"})
PATCH /api/tours/{id}	write	Zmiana tytułu, opisu, kategorii, lokalizacji, tagów, slug (czytelnego adresu), kolejności scen, sceny startowej i nazw scen
POST /api/tours/{id}/scenes	write	Przesłanie obrazu 360° jako surowej treści żądania
POST /api/content/{id}/visibility	write	Publikacja, udostępnienie tylko przez link lub zabezpieczenie hasłem spaceru albo projektu
GET /api/projects	read	Lista projektów konta (limit, cursor, profileId)
GET /api/projects/{id}	read	Jeden projekt z jego spacerami, obrazami, filmami i rzutami
GET /api/stats/{contentId}	stats	Wyświetlenia spaceru lub projektu (range w dniach)
GET /api/stats/{contentId}/export.csv	stats	To samo w formacie CSV (table = daily, scenes lub referrers)

Każdy inny endpoint odpowiada na żądanie z kluczem kodem 403 api_key_forbidden. Kontem, zespołem, płatnościami, kluczami API i webhookami zarządza się w przeglądarce.

Spacery

Lista. GET /api/tours?limit=50 zwraca {"items": […], "next": "…", "usage": {…}}. Aby pobrać następną stronę, przekaż wartość next jako cursor; usage zawiera liczbę scen konta i jego limity. Każdy element ma id, title, visibility, publishedAt, createdAt, updatedAt, profil i liczbę scen.

Odczyt. GET /api/tours/{id} zwraca pełny spacer: title, description, category, location, tags, slug, visibility (public, link lub password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes w kolejności, hotspots, settings, audio i links (player to adres do udostępniania, post – strona publiczna po publikacji).

Scena ma id, name, status (queued, processing, ready lub error), createdAt, opcjonalnie view (kierunek początkowy: yaw, pitch i fov w radianach), north (w radianach; 0 to środek obrazu, wartości rosną w prawo), a w trakcie przetwarzania stage i pct. Gotowa scena zawiera meta z poziomami kafelków i katalogiem głównym multimediów.

Tworzenie. POST /api/tours z treścią {"title": "Harbor View — Unit 4"} zwraca nowy spacer. Spacer bez tytułu otrzymuje nazwę „Spacer bez tytułu”.

Aktualizacja. PATCH /api/tours/{id} przyjmuje dowolne z poniższych pól i zwraca spacer:

• title, description, category, location, tags (tablica ciągów znaków), slug (adres publiczny: małe litery, cyfry i łączniki), commentsEnabled;
• order: tablica identyfikatorów scen w wybranej kolejności; pominięte sceny zachowują swoje miejsce za wymienionymi;
• startScene: identyfikator sceny; scena zostaje przeniesiona na początek (pierwsza scena jest sceną startową);
• coverScene: identyfikator sceny lub null dla sceny startowej;
• scenes: obiekt z kluczami w postaci identyfikatorów scen, zawierający name, view ({"yaw", "pitch", "fov"}) i north (w stopniach).

Wyślij If-Match: "<revision>" z ostatnio odczytaną wartością revision, aby odrzucić zapis nadpisujący cudzą zmianę: odpowiedzią będzie wtedy 409 revision_conflict z bieżącym spacerem w error.tour. Bez If-Match obowiązuje ostatni zapis.

Przesyłanie scen

POST /api/tours/{id}/scenes z plikiem obrazu jako surową treścią żądania. Nagłówki:

• Content-Type: image/jpeg, image/png, image/tiff lub image/webp;
• x-file-name: nazwa pliku zakodowana w formacie URL (encodeURIComponent); od niej pochodzi nazwa sceny, więc 01-living-room.jpg staje się sceną „01 living room”;
• x-pw-upload-batch i x-pw-upload-index (opcjonalne): gdy przesyłasz równolegle kilka plików z jednego wyboru, nadaj im ten sam identyfikator partii (litery, cyfry, - i _, maksymalnie 32 znaki) oraz ich indeks w wyborze; serwer zachowa wtedy tę kolejność bez względu na to, który plik zostanie przetworzony pierwszy. Bez tych nagłówków sceny są dodawane w kolejności nadejścia.

Akceptowane obrazy: panoramy equirectangular 2:1 o szerokości do limitu planu (8K w planie Darmowym, 16K od planu Pro wzwyż) lub panoramy stereo 1:1 w układzie góra-dół od planu Pro wzwyż (lewe oko na górze), o rozmiarze do 1 GiB. Odpowiedzią jest scena (status: "queued"). Przetwarzanie przebiega etapami: najpierw scena staje się widoczna (kafelki podglądu), potem pojawiają się kafelki w pełnej rozdzielczości („wyostrzanie”), a od planu Pro wzwyż także tekstury VR; oba etapy biegną równolegle i każdy może zakończyć się pierwszy. Pole meta.pending sceny, strumień zdarzeń i webhooki informują, które etapy wciąż trwają.

Błędy: 400 unsupported_format (plik nie jest w formacie JPG, PNG, TIFF ani WebP), 400 unsupported_ratio (proporcje inne niż 2:1 lub 1:1 góra-dół), 400 unreadable_image (uszkodzony plik), 402 plan_required (16K lub stereo w planie, który ich nie obejmuje), 402 quota_exceeded (limit scen konta), 413 file_too_large.

Postęp przetwarzania

GET /api/tours/{id}/events to strumień zdarzeń SSE (text/event-stream). Zdarzenia: hello po połączeniu, queue (pozycja oczekujących scen w kolejce i podsumowanie spaceru, co kilka sekund, dopóki coś jest przetwarzane), scene (status, stage, pct lub error) i tour (spacer się zmienił; odczytaj go ponownie). Do integracji serwer–serwer lepiej używać opisanych niżej webhooków.

Publikacja i widoczność

POST /api/content/{id}/visibility działa dla spacerów i projektów i zwraca treść:

• {"visibility": "link"} – dostępny tylko przez link (domyślne ustawienie każdego nowego spaceru);
• {"visibility": "public", "rightsAccepted": true} – widoczny na profilu i w sekcji Odkrywaj oraz indeksowany; wymagana jest category (najpierw ustaw ją przez PATCH), a Ty potwierdzasz, że masz prawo do publikacji obrazów. W przypadku projektu dodaj "tourIds": [...], aby opublikować razem z nim spacery;
• {"visibility": "password", "password": "…"} – od planu Pro wzwyż; pomiń password, aby zachować bieżące hasło.

Spacer w projekcie chronionym hasłem nie może stać się publiczny ani mieć własnego hasła (409 in_password_project); dostęp chroni hasło projektu.

Projekty

Obecnie projekty są dostępne przez API tylko do odczytu. GET /api/projects zwraca ich listę z polami id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount i datami; GET /api/projects/{id} dodaje description, location, tags, urls (public i link prywatny), tours z ich scenami oraz galerię: images, videos i floorplans ze znacznikami. Twórz projekty i dodawaj multimedia w studiu.

Statystyki

GET /api/stats/{contentId}?range=30 zwraca wyświetlenia spaceru lub projektu. Zakres danych zależy od planu: w planie Darmowym łączna liczba total od początku; w planie Pro seria daily uzupełniona zerami (from, to, maksymalnie 90 dni); w planach Office i Korporacyjnym do 365 dni oraz sources (strona, osadzenie, wejście bezpośrednie), devices (telefon, komputer, gogle VR), scenes i referrers osadzających witryn. …/export.csv?range=30&table=daily zwraca tabelę dzienną, table=scenes – wyświetlenia według scen, a table=referrers – witryny z osadzeniami. Wyświetlenia są liczone według adresu odwiedzającego i treści, raz na 30 minut; żadne dane osobowe nie są przechowywane.

Webhooki

W sekcji Ustawienia → API możesz dodać maksymalnie pięć webhooków. Wysyłamy podpisane żądanie POST z treścią JSON:

{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
 "data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}

Zdarzenie	Kiedy	Dane
scene.ready	Scena jest widoczna (kafelki podglądu)	pending: etapy, które wciąż trwają – refine (kafelki w pełnej rozdzielczości) i vr (tekstury dla gogli); [], gdy podgląd jest ostateczny
scene.sharpened	Kafelki w pełnej rozdzielczości są gotowe	stage: "refine", ok (false, gdy etap pominięto i scena pozostaje w jakości podglądu), pending
scene.vr_ready	Tekstury VR są gotowe	stage: "vr", ok, pending
scene.failed	Przetwarzanie ostatecznie się nie powiodło	error z przyczyną
ping	Przycisk „Wyślij test”	puste

Nagłówki: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, gdzie h1 to HMAC-SHA256 z ts + ":" + body obliczony przy użyciu sekretu webhooka (na dokładnie tych bajtach, które otrzymano), a także Prewalk-Event-Id i Prewalk-Event-Type. W trakcie rotacji sekretu nagłówek zawiera dwie wartości h1 (ts=…;h1=<new>;h1=<old>), dopóki poprzedni sekret nie wygaśnie: zaakceptuj dostawę, jeśli którakolwiek z nich przejdzie weryfikację. Zweryfikuj podpis, odrzuć znacznik czasu starszy niż kilka minut i usuwaj duplikaty według eventId: dostawa jest ponawiana, dopóki Twój endpoint nie odpowie kodem 2xx (dziesięć prób, najpierw po 30 s, potem w podwajanych odstępach, łącznie około czterech godzin), a treść ponowionej dostawy jest identyczna co do bajtu. Po 20 nieudanych dostawach z rzędu webhook zostaje wyłączony, a właściciel konta otrzymuje e-mail. Endpointy muszą używać https i mieć adres publiczny; przekierowania nie są obsługiwane. Sekret można zmienić; poprzedni pozostaje ważny przez 24 godziny.

Przykład krok po kroku

# 1. create a tour
curl -s https://prewalk.co/api/tours -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" -d '{"title":"Harbor View — Unit 4"}'

# 2. upload two scenes in order
curl -s https://prewalk.co/api/tours/$TOUR/scenes -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: image/jpeg" -H "x-file-name: 01-living-room.jpg" \
  -H "x-pw-upload-batch: sel-1" -H "x-pw-upload-index: 0" --data-binary @01-living-room.jpg
curl -s https://prewalk.co/api/tours/$TOUR/scenes -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: image/jpeg" -H "x-file-name: 02-kitchen.jpg" \
  -H "x-pw-upload-batch: sel-1" -H "x-pw-upload-index: 1" --data-binary @02-kitchen.jpg

# 3. set a category and publish
curl -s -X PATCH https://prewalk.co/api/tours/$TOUR -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" -d '{"category":"real-estate","location":"Istanbul"}'
curl -s https://prewalk.co/api/content/$TOUR/visibility -H "Authorization: Bearer $PW_KEY" \
  -H "Content-Type: application/json" -d '{"visibility":"public","rightsAccepted":true}'

# 4. views of the last 30 days
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"

Osadzanie

Osadzanie nie wymaga klucza: każdy spacer ma adres https://prewalk.co/embed/{id}, a embed.js dopasowuje rozmiar ramki i otwiera ją na pełnym ekranie na Twojej stronie. Witryny, na których mogą się wyświetlać Twoje osadzenia, ustawisz w sekcji Ustawienia → Identyfikacja wizualna. Szczegóły znajdziesz w przewodniku „Osadź wirtualny spacer, projekt lub portfolio na swojej stronie”.

Kody błędów

Status	Kod	Znaczenie
400	invalid_request	Brak pola lub pole jest nieprawidłowe; field wskazuje, które
400	unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content	Niespełnione warunki przesłania lub publikacji (projekt potrzebuje publicznego spaceru, obrazu lub filmu)
401	unauthorized, invalid_api_key	Brak klucza albo klucz jest nieprawidłowy lub unieważniony
402	plan_required, quota_exceeded	Plan nie obejmuje funkcji lub osiągnięto limit (feature lub limit wskazuje, który)
403	api_key_forbidden, api_scope_missing	Endpoint nie jest dostępny dla kluczy lub klucz nie ma wymaganego zakresu
404	not_found	Zasób nie należy do Ciebie, został usunięty lub taki identyfikator nie istnieje
409	revision_conflict, slug_taken, in_password_project	Równoczesna edycja (dołączony jest bieżący spacer), adres jest zajęty, reguła hasła projektu
413	file_too_large	Przekroczono limit rozmiaru
429	rate_limited	Zbyt wiele żądań; odczekaj tyle sekund, ile podaje Retry-After
503	maintenance	Trwa aktualizacja serwisu Prewalk; spróbuj ponownie po minucie

Zmiany

• 10 listopada 2026: projekt, który ma tylko obrazy lub filmy, można opublikować lub chronić hasłem. Projekt, który nie ma nic do pokazania, zwraca 400 project_needs_content – zarówno publiczny, jak i chroniony hasłem; ten kod zastępuje project_needs_public_tour i project_needs_tour, które nie są już wysyłane. GET /api/projects dodaje videoCount.
• 22 października 2026: scene.ready zawiera pending; nowe zdarzenia scene.sharpened i scene.vr_ready; nagłówki kolejności przesyłania x-pw-upload-batch i x-pw-upload-index; GET /api/me z kluczem opisuje tylko konto klucza.

Masz pytania lub brakuje Ci jakiegoś endpointu? Napisz na hello@prewalk.co.