Přeskočit na obsah
← Zpět na návody

Referenční příručka API

10 min čtení

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žívejte app.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čku Authorization.
  • 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 429 s hlavičkou Retry-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 cestaOprávněníCo dělá
GET /api/mereadÚčet, profily a oprávnění klíče
GET /api/toursreadSeznam prohlídek účtu (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}readJedna prohlídka se scénami, hotspoty a nastavením
GET /api/tours/{id}/eventsreadPrůběh zpracování jako proud server-sent events
POST /api/tourswriteVytvoření prohlídky ({"title": "…"})
PATCH /api/tours/{id}writeZmě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}/sceneswriteNahrání obrázku 360° jako surového těla
POST /api/content/{id}/visibilitywriteZveřejnění, nastavení jen přes odkaz nebo ochrana heslem u prohlídky či projektu
GET /api/projectsreadSeznam projektů účtu (limit, cursor, profileId)
GET /api/projects/{id}readJeden projekt s prohlídkami, obrázky, videi a půdorysy
GET /api/stats/{contentId}statsZobrazení prohlídky nebo projektu (range ve dnech)
GET /api/stats/{contentId}/export.csvstatsTotéž 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, nebo null pro počáteční scénu;
  • scenes: objekt s klíči podle ID scén s hodnotami name, view ({"yaw", "pitch", "fov"}) a north (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/tiff nebo image/webp;
  • x-file-name: název souboru zakódovaný pro URL (encodeURIComponent); scéna dostane název podle něj, takže z 01-living-room.jpg bude „01 living room“;
  • x-pw-upload-batch a x-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řes PATCH) 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ž password vynechá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álostKdyData
scene.readyScé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.sharpenedDlaž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_readyTextury pro VR jsou na místěstage: "vr", ok, pending
scene.failedZpracování definitivně selhaloerror s důvodem
pingTlačí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

StatusKódVýznam
400invalid_requestPole chybí nebo je neplatné; field uvádí které
400unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_contentNesplněné předpoklady pro nahrání nebo zveřejnění (projekt potřebuje veřejnou prohlídku, obrázek nebo video)
401unauthorized, invalid_api_keyKlíč chybí úplně, nebo je chybně utvořený či zneplatněný
402plan_required, quota_exceededTarif funkci nezahrnuje, nebo byl dosažen limit (feature nebo limit uvádí který)
403api_key_forbidden, api_scope_missingEndpoint není pro klíče přístupný, nebo klíči chybí oprávnění
404not_foundNepatří vám, je smazané, nebo takové ID neexistuje
409revision_conflict, slug_taken, in_password_projectSouběžná úprava (aktuální prohlídka je přiložena), adresa je obsazená, pravidlo hesla projektu
413file_too_largePřekročen limit velikosti
429rate_limitedPříliš mnoho požadavků; počkejte Retry-After sekund
503maintenancePrewalk 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 nahrazuje project_needs_public_tour a project_needs_tour, které se už neposílají. GET /api/projects přidává videoCount.
  • 22. 10. 2026: scene.ready nese pending; nové události scene.sharpened a scene.vr_ready; hlavičky pro pořadí nahrávání x-pw-upload-batch a x-pw-upload-index; GET /api/me s 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

  • Co je fotografie 360°?

    Co je fotografie 360°? Snímek 2:1, který ukazuje všechny směry z jednoho bodu (360° × 180°). Jak ji pořídit, jak ji zobrazit a čím se liší od panoramatu.