Referenční příručka API
API Prewalk je součástí tarifu Enterprise. S API klíčem může váš vlastní software vytvářet prohlídky, nahrávat scény, zveřejňovat, číst projekty a statistiky a v každé fázi zpracování dostávat podepsaný webhook. Tato stránka je referenční příručka; studio i veřejný přehrávač fungují dál jako dosud.
Základní URL a konvence
- Základní URL:
https://prewalk.co. Nepoužívejteapp.prewalk.co: přesměrovává (308) a většina HTTP klientů při přesměrování na jiného hostitele zahodí hlavičkuAuthorization. - Formát: JSON na vstupu i výstupu (
Content-Type: application/json), kromě nahrávání scén, které posílá obrázek jako surové tělo požadavku. - ID mají 12 malých písmen a číslic, například
teeg8crtm0u0. Data jsou ve formátu ISO 8601 v UTC. - Chyby vypadají vždy stejně: HTTP status a
{"error": {"code": "…", "message": "…"}}; chyby validace přidávajífield. Kódy najdete na konci této stránky. - Limit požadavků: 600 požadavků za minutu na klíč. Nad ním dostanete
429s hlavičkouRetry-After(v sekundách).
Ověření
Klíč vytvoříte v Nastavení → API (vlastník účtu nebo administrátor, Enterprise). Klíč patří k účtu, lze ho omezit na jeden profil značky a má až tři oprávnění: read, write a stats. Celý klíč se zobrazí jen jednou; seznam ukazuje pouze jeho prefix. Na účet lze mít až 20 klíčů; zneplatněný klíč přestane fungovat okamžitě.
Authorization: Bearer pw_…
Klíč jedná za jeden účet. GET /api/me popisuje, co klíč vidí: účet a limity jeho tarifu, profily tohoto účtu, profil, za který klíč jedná (actor), a samotný klíč s jeho oprávněními. Nikdy nevrací e-mail vlastníka klíče ani jeho další účty.
Endpointy
| Metoda a cesta | Oprávnění | Co dělá |
|---|---|---|
GET /api/me | read | Účet, profily a oprávnění klíče |
GET /api/tours | read | Seznam prohlídek účtu (limit ≤ 50, cursor, profileId) |
GET /api/tours/{id} | read | Jedna prohlídka se scénami, hotspoty a nastavením |
GET /api/tours/{id}/events | read | Průběh zpracování jako proud server-sent events |
POST /api/tours | write | Vytvoření prohlídky ({"title": "…"}) |
PATCH /api/tours/{id} | write | Změna názvu, popisu, kategorie, lokality, štítků, slug (čitelná adresa), pořadí scén, počáteční scény a názvů scén |
POST /api/tours/{id}/scenes | write | Nahrání obrázku 360° jako surového těla |
POST /api/content/{id}/visibility | write | Zveřejnění, nastavení jen přes odkaz nebo ochrana heslem u prohlídky či projektu |
GET /api/projects | read | Seznam projektů účtu (limit, cursor, profileId) |
GET /api/projects/{id} | read | Jeden projekt s prohlídkami, obrázky, videi a půdorysy |
GET /api/stats/{contentId} | stats | Zobrazení prohlídky nebo projektu (range ve dnech) |
GET /api/stats/{contentId}/export.csv | stats | Totéž jako CSV (table = daily, scenes nebo referrers) |
Všechny ostatní endpointy odpovídají na požadavek s klíčem 403 api_key_forbidden. Účet, tým, fakturace, API klíče a webhooky se spravují v prohlížeči.
Prohlídky
Seznam. GET /api/tours?limit=50 vrací {"items": […], "next": "…", "usage": {…}}. Hodnotu next předejte zpět jako cursor pro další stránku; usage obsahuje počet scén účtu a jeho limity. Každá položka má id, title, visibility, publishedAt, createdAt, updatedAt, profil a počet scén.
Čtení. GET /api/tours/{id} vrací celou prohlídku: title, description, category, location, tags, slug, visibility (public, link nebo password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes v pořadí, hotspots, settings, audio a links (player je adresa ke sdílení, post veřejná stránka po zveřejnění).
Scéna má id, name, status (queued, processing, ready nebo error), createdAt, volitelně view (výchozí směr pohledu: yaw, pitch a fov v radiánech), north (v radiánech; 0 je střed obrázku, hodnota roste doprava) a během zpracování stage a pct. Připravená scéna nese meta s úrovněmi dlaždic a kořenovou adresou médií.
Vytvoření. POST /api/tours s {"title": "Harbor View — Unit 4"} vrací novou prohlídku. Bez názvu dostane název „Untitled tour“.
Úprava. PATCH /api/tours/{id} přijímá kterékoli z těchto polí a vrací prohlídku:
title,description,category,location,tags(pole řetězců),slug(veřejná adresa, malá písmena, číslice a pomlčky),commentsEnabled;order: pole ID scén v požadovaném pořadí; scény, které vynecháte, si ponechají své místo za uvedenými;startScene: ID scény; přesune se na začátek (první scéna je počáteční scéna);coverScene: ID scény, nebonullpro počáteční scénu;scenes: objekt s klíči podle ID scén s hodnotaminame,view({"yaw", "pitch", "fov"}) anorth(ve stupních).
Pošlete If-Match: "<revision>" s naposledy přečtenou hodnotou revision, aby byl zápis přes cizí změnu odmítnut: odpověď je pak 409 revision_conflict s aktuální prohlídkou v error.tour. Bez If-Match platí poslední zápis.
Nahrávání scén
POST /api/tours/{id}/scenes se souborem obrázku jako surovým tělem. Hlavičky:
Content-Type:image/jpeg,image/png,image/tiffneboimage/webp;x-file-name: název souboru zakódovaný pro URL (encodeURIComponent); scéna dostane název podle něj, takže z01-living-room.jpgbude „01 living room“;x-pw-upload-batchax-pw-upload-index(volitelné): když nahráváte několik souborů jednoho výběru paralelně, dejte jim stejné ID dávky (písmena, číslice,-a_, nejvýše 32 znaků) a jejich pořadí ve výběru; server pak toto pořadí zachová bez ohledu na to, který soubor doběhne první. Bez nich se scény přidávají v pořadí, v jakém dorazí.
Přijímané obrázky: ekvirektangulární panoramata 2:1 do šířky povolené tarifem (8K v tarifu Zdarma, 16K od tarifu Pro výše), nebo stereo panoramata 1:1 top-bottom od tarifu Pro výše (levé oko nahoře), do 1 GiB. Odpovědí je scéna (status: "queued"). Zpracování probíhá ve fázích: scéna se nejdřív zobrazí (náhledové dlaždice), pak dorazí dlaždice v plném rozlišení („zaostření“) a od tarifu Pro výše textury pro VR; obě fáze běží souběžně a kterákoli může skončit dřív. Které fáze ještě běží, zjistíte z meta.pending scény, z proudu událostí a z webhooků.
Chyby: 400 unsupported_format (není JPG, PNG, TIFF ani WebP), 400 unsupported_ratio (není 2:1 ani 1:1 top-bottom), 400 unreadable_image (poškozený soubor), 402 plan_required (16K nebo stereo v tarifu, který je nezahrnuje), 402 quota_exceeded (limit scén účtu), 413 file_too_large.
Průběh zpracování
GET /api/tours/{id}/events je proud server-sent events (text/event-stream). Události: hello při připojení, queue (pozice čekajících scén ve frontě a souhrn prohlídky, každých několik sekund, dokud něco běží), scene (status, stage, pct nebo error) a tour (prohlídka se změnila; načtěte ji znovu). Pro integraci mezi servery dejte přednost webhookům níže.
Zveřejnění a viditelnost
POST /api/content/{id}/visibility funguje pro prohlídky i projekty a vrací daný obsah:
{"visibility": "link"}– dostupné jen přes svou adresu (výchozí stav každé nové prohlídky);{"visibility": "public", "rightsAccepted": true}– na profilu, v sekci Prozkoumat a indexovatelné; je nutnácategory(nastavte ji nejdřív přesPATCH) a potvrzujete, že máte právo obrázky zveřejnit. U projektu přidejte"tourIds": [...], abyste spolu s ním zveřejnili i prohlídky;{"visibility": "password", "password": "…"}– od tarifu Pro výše; kdyžpasswordvynecháte, zůstane stávající heslo.
Prohlídka uvnitř projektu chráněného heslem nemůže být veřejná ani mít vlastní heslo (409 in_password_project); přístup hlídá heslo projektu.
Projekty
Projekty jsou zatím přes API jen ke čtení. GET /api/projects je vypíše s id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount a datumy; GET /api/projects/{id} přidává description, location, tags, urls (public a soukromý odkaz), tours s jejich scénami a galerii images, videos a floorplans se špendlíky. Projekty vytvářejte a média přidávejte ve studiu.
Statistiky
GET /api/stats/{contentId}?range=30 vrací zobrazení prohlídky nebo projektu. Co dostanete, závisí na tarifu: v tarifu Zdarma celkový počet total za celou dobu; v tarifu Pro řadu daily doplněnou nulami (from, to, až 90 dní); v tarifech Office a Enterprise až 365 dní a k tomu sources (stránka, vložení, přímý přístup), devices (telefon, počítač, VR brýle), scenes a weby s vloženým obsahem v referrers. …/export.csv?range=30&table=daily vrací denní tabulku, table=scenes zobrazení po scénách a table=referrers weby, které obsah vkládají. Zobrazení se počítají podle adresy návštěvníka a obsahu, jednou za 30 minut; nic osobního se neukládá.
Webhooky
V Nastavení → API přidáte až pět webhooků. Posíláme podepsaný POST s tělem JSON:
{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
"data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}
| Událost | Kdy | Data |
|---|---|---|
scene.ready | Scéna je viditelná (náhledové dlaždice) | pending: fáze, které ještě běží – refine (dlaždice v plném rozlišení) a vr (textury pro VR brýle); [], když je náhled konečný |
scene.sharpened | Dlaždice v plném rozlišení jsou na místě | stage: "refine", ok (false, když byla fáze vynechána a scéna zůstává v kvalitě náhledu), pending |
scene.vr_ready | Textury pro VR jsou na místě | stage: "vr", ok, pending |
scene.failed | Zpracování definitivně selhalo | error s důvodem |
ping | Tlačítko „Poslat test“ | prázdné |
Hlavičky: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, kde h1 je HMAC-SHA256 z ts + ":" + body s tajným klíčem vašeho webhooku (počítaný přesně nad přijatými bajty), a dále Prewalk-Event-Id a Prewalk-Event-Type. Během rotace tajného klíče nese hlavička dvě hodnoty h1 (ts=…;h1=<new>;h1=<old>), dokud předchozí klíč nevyprší: doručení přijměte, pokud se ověří kterákoli z nich. Ověřte podpis, odmítněte časové razítko starší než několik minut a odstraňujte duplicity podle eventId: doručení se opakuje, dokud váš endpoint neodpoví 2xx (deset pokusů, nejdřív po 30 s, pak s dvojnásobným odstupem, celkem asi čtyři hodiny), a opakované tělo je bajtově shodné. Po 20 neúspěšných doručeních za sebou se webhook vypne a vlastník účtu dostane e-mail. Endpointy musí používat https na veřejné adrese; přesměrování se nesledují. Tajný klíč lze rotovat; předchozí zůstává platný 24 hodin.
Ukázkový postup
# 1. vytvořte prohlídku
curl -s https://prewalk.co/api/tours -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: application/json" -d '{"title":"Harbor View — Unit 4"}'
# 2. nahrajte dvě scény v daném pořadí
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. nastavte kategorii a zveřejněte
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. zobrazení za posledních 30 dní
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"
Vložení na web
Vložení na web nepotřebuje klíč: každá prohlídka má https://prewalk.co/embed/{id} a embed.js nastaví velikost rámce a na vaší stránce ho otevře na celou obrazovku. Které weby smějí zobrazovat vaše vložené prohlídky, nastavíte v Nastavení → Vlastní značka. Podrobnosti najdete v návodu k vložení na web.
Chybové kódy
| Status | Kód | Význam |
|---|---|---|
| 400 | invalid_request | Pole chybí nebo je neplatné; field uvádí které |
| 400 | unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content | Nesplněné předpoklady pro nahrání nebo zveřejnění (projekt potřebuje veřejnou prohlídku, obrázek nebo video) |
| 401 | unauthorized, invalid_api_key | Klíč chybí úplně, nebo je chybně utvořený či zneplatněný |
| 402 | plan_required, quota_exceeded | Tarif funkci nezahrnuje, nebo byl dosažen limit (feature nebo limit uvádí který) |
| 403 | api_key_forbidden, api_scope_missing | Endpoint není pro klíče přístupný, nebo klíči chybí oprávnění |
| 404 | not_found | Nepatří vám, je smazané, nebo takové ID neexistuje |
| 409 | revision_conflict, slug_taken, in_password_project | Souběžná úprava (aktuální prohlídka je přiložena), adresa je obsazená, pravidlo hesla projektu |
| 413 | file_too_large | Překročen limit velikosti |
| 429 | rate_limited | Příliš mnoho požadavků; počkejte Retry-After sekund |
| 503 | maintenance | Prewalk se aktualizuje; zkuste to znovu za minutu |
Změny
- 10. 11. 2026: projekt lze zveřejnit nebo chránit heslem i jen s obrázky či videi. Projekt, který nemá co ukázat, vrací
400 project_needs_content, veřejný i chráněný heslem; tento kód nahrazujeproject_needs_public_touraproject_needs_tour, které se už neposílají.GET /api/projectspřidávávideoCount. - 22. 10. 2026:
scene.readynesepending; nové událostiscene.sharpenedascene.vr_ready; hlavičky pro pořadí nahráváníx-pw-upload-batchax-pw-upload-index;GET /api/mes klíčem popisuje jen účet daného klíče.
Máte otázky, nebo vám chybí endpoint? Napište na hello@prewalk.co.
Sdílet: Sdílet na X LinkedIn WhatsApp



