API-dokumentaatio
Prewalkin API kuuluu Enterprise-pakettiin. API-avaimen avulla oma ohjelmistosi voi luoda kierroksia, ladata näkymiä palveluun, julkaista, lukea projekteja ja tilastoja sekä saada allekirjoitetun webhookin jokaisessa käsittelyvaiheessa. Tämä sivu on referenssi; studio ja julkinen katselin toimivat kuten ennenkin.
Perus-URL ja käytännöt
- Perus-URL:
https://prewalk.co. Älä käytä osoitettaapp.prewalk.co: se tekee uudelleenohjauksen (308), ja useimmat HTTP-asiakkaat pudottavatAuthorization-otsakkeen, kun uudelleenohjaus vie toiselle palvelimelle. - Muoto: JSON sisään ja ulos (
Content-Type: application/json), paitsi näkymien latauksissa, joissa kuva lähetetään sellaisenaan pyynnön runkona. - Tunnisteet ovat 12 merkin mittaisia ja koostuvat pienistä kirjaimista ja numeroista, esimerkiksi
teeg8crtm0u0. Päivämäärät ovat ISO 8601 -muodossa UTC-ajassa. - Virheet näyttävät aina samalta: HTTP-tila ja
{"error": {"code": "…", "message": "…"}}; validointivirheisiin lisätäänfield. Koodit on lueteltu tämän sivun lopussa. - Pyyntöraja: 600 pyyntöä minuutissa avainta kohden. Sen ylittyessä saat vastauksen
429jaRetry-After-otsakkeen (sekunteina).
Tunnistautuminen
Luo avain kohdassa Asetukset → API (tilin omistaja tai ylläpitäjä, Enterprise). Avain kuuluu tilille, sen voi rajata yhteen brändiprofiiliin, ja sillä on enintään kolme käyttöoikeutta: read, write ja stats. Koko avain näytetään vain kerran; luettelossa näkyy vain sen etuliite. Tilillä voi olla enintään 20 avainta; peruttu avain lakkaa toimimasta heti.
Authorization: Bearer pw_…
Avain toimii yhden tilin puolesta. GET /api/me kertoo, mitä avain näkee: tilin ja sen paketin rajat, tilin profiilit, profiilin, jona avain toimii (actor), sekä itse avaimen käyttöoikeuksineen. Se ei koskaan palauta avaimen omistajan sähköpostiosoitetta eikä hänen muita tilejään.
Päätepisteet
| Metodi ja polku | Käyttöoikeus | Mitä se tekee |
|---|---|---|
GET /api/me | read | Avaimen tili, profiilit ja käyttöoikeudet |
GET /api/tours | read | Listaa tilin kierrokset (limit ≤ 50, cursor, profileId) |
GET /api/tours/{id} | read | Yksi kierros näkymineen, hotspotteineen ja asetuksineen |
GET /api/tours/{id}/events | read | Käsittelyn eteneminen server-sent events -tapahtumavirtana |
POST /api/tours | write | Luo kierros ({"title": "…"}) |
PATCH /api/tours/{id} | write | Muuta otsikkoa, kuvausta, luokkaa, sijaintia, tunnisteita, slug-arvoa (luettava osoite), näkymien järjestystä, aloitusnäkymää ja näkymien nimiä |
POST /api/tours/{id}/scenes | write | Lataa 360°-kuva sellaisenaan pyynnön runkona |
POST /api/content/{id}/visibility | write | Julkaise kierros tai projekti, jaa se vain linkillä tai suojaa se salasanalla |
GET /api/projects | read | Listaa tilin projektit (limit, cursor, profileId) |
GET /api/projects/{id} | read | Yksi projekti kierroksineen, kuvineen, videoineen ja pohjapiirroksineen |
GET /api/stats/{contentId} | stats | Kierroksen tai projektin katselukerrat (range päivinä) |
GET /api/stats/{contentId}/export.csv | stats | Samat tiedot CSV-muodossa (table = daily, scenes tai referrers) |
Kaikki muut päätepisteet vastaavat avaimella tehtyyn pyyntöön 403 api_key_forbidden. Tiliä, tiimiä, laskutusta, API-avaimia ja webhookeja hallitaan selaimessa.
Kierrokset
Listaus. GET /api/tours?limit=50 palauttaa {"items": […], "next": "…", "usage": {…}}. Anna next takaisin cursor-arvona saadaksesi seuraavan sivun; usage sisältää tilin näkymämäärän ja rajat. Jokaisella kohteella on id, title, visibility, publishedAt, createdAt, updatedAt, profiili ja näkymämäärät.
Luku. GET /api/tours/{id} palauttaa koko kierroksen: title, description, category, location, tags, slug, visibility (public, link tai password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes järjestyksessä, hotspots, settings, audio ja links (player on jaettava osoite, post julkinen sivu, kun kierros on julkaistu).
Näkymällä on id, name, status (queued, processing, ready tai error), createdAt, valinnaisesti view (aloituskuvakulma: yaw, pitch ja fov radiaaneina), north (radiaaneina; 0 on kuvan keskikohta, ja arvo kasvaa oikealle) sekä käsittelyn aikana stage ja pct. Valmiilla näkymällä on meta, jossa ovat sen tiilitasot ja median juuripolku.
Luonti. POST /api/tours rungolla {"title": "Harbor View — Unit 4"} palauttaa uuden kierroksen. Ilman otsikkoa sen nimeksi tulee ”Nimetön kierros”.
Päivitys. PATCH /api/tours/{id} hyväksyy minkä tahansa näistä kentistä ja palauttaa kierroksen:
title,description,category,location,tags(merkkijonotaulukko),slug(julkinen osoite: pieniä kirjaimia, numeroita ja yhdysmerkkejä),commentsEnabled;order: taulukko näkymätunnisteita haluamassasi järjestyksessä; näkymät, jotka jätät pois, säilyttävät paikkansa luettelemiesi näkymien jälkeen;startScene: näkymätunniste; näkymä siirretään ensimmäiseksi (ensimmäinen näkymä on aloitusnäkymä);coverScene: näkymätunniste tainull, jolloin kansikuvana käytetään aloitusnäkymää;scenes: objekti, jonka avaimina ovat näkymätunnisteet ja jossa onname,view({"yaw", "pitch", "fov"}) janorth(asteina).
Lähetä If-Match: "<revision>" viimeksi lukemallasi revision-arvolla, niin kirjoitus hylätään, jos joku muu on ehtinyt muuttaa kierrosta: vastaus on silloin 409 revision_conflict, ja nykyinen kierros on kentässä error.tour. Ilman If-Match-otsaketta viimeisin kirjoittaja voittaa.
Näkymien lataaminen
POST /api/tours/{id}/scenes, jonka runkona on kuvatiedosto sellaisenaan. Otsakkeet:
Content-Type:image/jpeg,image/png,image/tifftaiimage/webp;x-file-name: tiedostonimi URL-koodattuna (encodeURIComponent); näkymä nimetään sen mukaan, joten01-living-room.jpgsaa nimen ”01 living room”;x-pw-upload-batchjax-pw-upload-index(valinnaisia): kun lataat saman valinnan useita tiedostoja rinnakkain, anna niille sama erätunniste (kirjaimia, numeroita,-ja_, enintään 32 merkkiä) ja niiden järjestysnumero valinnassa; palvelin säilyttää silloin järjestyksen riippumatta siitä, mikä tiedosto valmistuu ensin. Ilman niitä näkymät lisätään saapumisjärjestyksessä.
Hyväksytyt kuvat: 2:1-kuvasuhteiset ekvirektangulaariset panoraamat paketin leveysrajaan asti (ilmaisessa paketissa 8K, Pro-paketista alkaen 16K) tai 1:1 ylä-ala-stereopanoraamat Pro-paketista alkaen (vasen silmä ylhäällä), enintään 1 GiB. Vastauksena on näkymä (status: "queued"). Käsittely etenee vaiheittain: näkymä tulee ensin näkyviin (esikatselutiilet), sitten saapuvat täyden resoluution tiilet (”tarkennus”) ja Pro-paketista alkaen VR-tekstuurit; nämä kaksi ajetaan rinnakkain, ja kumpi tahansa voi valmistua ensin. Näkymän meta.pending, tapahtumavirta ja webhookit kertovat, mitkä vaiheet ovat vielä käynnissä.
Virheet: 400 unsupported_format (ei JPG-, PNG-, TIFF- tai WebP-tiedosto), 400 unsupported_ratio (ei 2:1 eikä 1:1 ylä-ala), 400 unreadable_image (vioittunut tiedosto), 402 plan_required (16K tai stereo paketissa, johon se ei sisälly), 402 quota_exceeded (tilin näkymäraja), 413 file_too_large.
Käsittelyn eteneminen
GET /api/tours/{id}/events on server-sent events -tapahtumavirta (text/event-stream). Tapahtumat: hello yhdistettäessä, queue (odottavien näkymien jonopaikka ja yhteenveto kierroksesta muutaman sekunnin välein, kun jokin on käynnissä), scene (status, stage, pct tai error) ja tour (kierros muuttui; lue se uudelleen). Palvelinten väliseen integraatioon kannattaa käyttää alla kuvattuja webhookeja.
Julkaisu ja näkyvyys
POST /api/content/{id}/visibility toimii kierroksille ja projekteille ja palauttaa sisällön:
{"visibility": "link"}– avautuu vain osoitteensa kautta (jokaisen uuden kierroksen oletus);{"visibility": "public", "rightsAccepted": true}– näkyy profiilissa ja Tutki-osiossa ja on hakukoneiden indeksoitavissa;categoryvaaditaan (aseta se ensinPATCH-pyynnöllä), ja vahvistat, että sinulla on oikeus julkaista kuvat. Kun julkaiset projektin, lisää"tourIds": [...], niin kierrokset julkaistaan sen mukana;{"visibility": "password", "password": "…"}– Pro-paketista alkaen; jätäpasswordpois, niin nykyinen salasana säilyy.
Salasanalla suojatun projektin sisällä olevaa kierrosta ei voi muuttaa julkiseksi eikä sille voi asettaa omaa salasanaa (409 in_password_project); pääsyn ratkaisee projektin salasana.
Projektit
Projektit ovat API:n kautta toistaiseksi vain luettavissa. GET /api/projects listaa ne kentillä id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount ja päivämäärät; GET /api/projects/{id} lisää description, location, tags, urls (public ja yksityinen linkki), kierrokset tours näkymineen sekä gallerian images, videos ja floorplans kiinnityspisteineen. Luo projektit ja lisää media studiossa.
Tilastot
GET /api/stats/{contentId}?range=30 palauttaa kierroksen tai projektin katselukerrat. Saamasi tiedot riippuvat paketista: ilmaisessa paketissa kaikkien aikojen total; Pro-paketissa nollilla täydennetty daily-sarja (from, to, enintään 90 päivää); Office- ja Enterprise-paketeissa enintään 365 päivää sekä sources (sivu, upotus, suora), devices (puhelin, tietokone, VR-lasit), scenes ja upottavat sivustot referrers. …/export.csv?range=30&table=daily antaa päivittäisen taulukon, table=scenes katselukerrat näkymittäin ja table=referrers upottavat sivustot. Katselukerrat lasketaan kävijän osoitteen ja sisällön mukaan kerran 30 minuutissa; mitään henkilötietoja ei tallenneta.
Webhookit
Lisää enintään viisi webhookia kohdassa Asetukset → API. Lähetämme allekirjoitetun POST-pyynnön, jonka runkona on JSON:
{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
"data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}
| Tapahtuma | Milloin | Tiedot |
|---|---|---|
scene.ready | Näkymä on näkyvissä (esikatselutiilet) | pending: vielä käynnissä olevat vaiheet – refine (täyden resoluution tiilet) ja vr (VR-lasien tekstuurit); [], kun esikatselu on lopullinen |
scene.sharpened | Täyden resoluution tiilet ovat paikallaan | stage: "refine", ok (false, kun vaihe jätettiin pois ja näkymä jää esikatselulaatuun), pending |
scene.vr_ready | VR-tekstuurit ovat paikallaan | stage: "vr", ok, pending |
scene.failed | Käsittely epäonnistui lopullisesti | error ja syy |
ping | ”Lähetä testi” -painike | tyhjä |
Otsakkeet: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, jossa h1 on HMAC-SHA256 arvosta ts + ":" + body webhookin salaisuudella (laskettuna täsmälleen vastaanottamistasi tavuista), sekä Prewalk-Event-Id ja Prewalk-Event-Type. Kun salaisuuden vaihto on käynnissä, otsakkeessa on kaksi h1-arvoa (ts=…;h1=<new>;h1=<old>), kunnes edellinen salaisuus vanhenee: hyväksy toimitus, jos jokin niistä täsmää. Tarkista allekirjoitus, hylkää muutamaa minuuttia vanhempi aikaleima ja poista kaksoiskappaleet eventId-arvon perusteella: toimitusta yritetään uudelleen, kunnes päätepisteesi vastaa 2xx-koodilla (kymmenen yritystä, ensin 30 s ja sitten aina kaksinkertainen väli, yhteensä noin neljä tuntia), ja uudelleen lähetetty runko on tavu tavulta sama. Kun 20 toimitusta peräkkäin epäonnistuu, webhook poistetaan käytöstä ja tilin omistaja saa sähköpostin. Päätepisteen on käytettävä https-protokollaa ja oltava julkisessa osoitteessa; uudelleenohjauksia ei seurata. Salaisuuden voi vaihtaa; edellinen pysyy voimassa 24 tuntia.
Esimerkki vaihe vaiheelta
# 1. luo kierros
curl -s https://prewalk.co/api/tours -H "Authorization: Bearer $PW_KEY" \
-H "Content-Type: application/json" -d '{"title":"Harbor View — Unit 4"}'
# 2. lataa kaksi näkymää järjestyksessä
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. aseta luokka ja julkaise
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. viimeisten 30 päivän katselukerrat
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"
Upottaminen
Upottaminen ei vaadi avainta: jokaisella kierroksella on osoite https://prewalk.co/embed/{id}, ja embed.js mitoittaa kehyksen ja avaa sen koko näytön tilaan sivullasi. Sitä, millä verkkosivustoilla upotuksesi saavat näkyä, hallitaan kohdassa Asetukset → Brändäys. Lisätietoja on upotusoppaassa.
Virhekoodit
| Tila | Koodi | Merkitys |
|---|---|---|
| 400 | invalid_request | Kenttä puuttuu tai on virheellinen; field kertoo, mikä |
| 400 | unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content | Latauksen tai julkaisun ennakkoehdot (projektissa on oltava julkinen kierros, kuva tai video) |
| 401 | unauthorized, invalid_api_key | Avain puuttuu kokonaan, tai avain on virheellinen tai peruttu |
| 402 | plan_required, quota_exceeded | Paketista puuttuu ominaisuus, tai raja on täynnä (feature tai limit kertoo, mikä) |
| 403 | api_key_forbidden, api_scope_missing | Päätepiste ei ole avainten käytettävissä, tai avaimelta puuttuu käyttöoikeus |
| 404 | not_found | Ei sinun, poistettu tai tunnistetta ei ole olemassa |
| 409 | revision_conflict, slug_taken, in_password_project | Samanaikainen muokkaus (nykyinen kierros on mukana), osoite on jo käytössä, projektin salasanasääntö |
| 413 | file_too_large | Kokoraja ylittyy |
| 429 | rate_limited | Liian monta pyyntöä; odota Retry-After sekuntia |
| 503 | maintenance | Prewalkia päivitetään; yritä uudelleen minuutin kuluttua |
Muutokset
- 10.11.2026: projektin voi julkaista tai suojata salasanalla pelkillä kuvilla tai videoilla. Projekti, jossa ei ole mitään näytettävää, vastaa
400 project_needs_content, oli se julkinen tai salasanalla suojattu; koodi korvaa kooditproject_needs_public_tourjaproject_needs_tour, joita ei enää lähetetä.GET /api/projectslisää kentänvideoCount. - 22.10.2026:
scene.readysisältääpending-kentän; uudet tapahtumatscene.sharpenedjascene.vr_ready; latausjärjestyksen otsakkeetx-pw-upload-batchjax-pw-upload-index; avaimella kutsuttunaGET /api/mekuvaa vain avaimen tilin.
Kysyttävää tai puuttuuko jokin päätepiste? Kirjoita osoitteeseen hello@prewalk.co.



