Siirry sisältöön
← Takaisin oppaisiin

API-dokumentaatio

9 min lukuaika

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ä osoitetta app.prewalk.co: se tekee uudelleenohjauksen (308), ja useimmat HTTP-asiakkaat pudottavat Authorization-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ään field. Koodit on lueteltu tämän sivun lopussa.
  • Pyyntöraja: 600 pyyntöä minuutissa avainta kohden. Sen ylittyessä saat vastauksen 429 ja Retry-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 polkuKäyttöoikeusMitä se tekee
GET /api/mereadAvaimen tili, profiilit ja käyttöoikeudet
GET /api/toursreadListaa tilin kierrokset (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}readYksi kierros näkymineen, hotspotteineen ja asetuksineen
GET /api/tours/{id}/eventsreadKäsittelyn eteneminen server-sent events -tapahtumavirtana
POST /api/tourswriteLuo kierros ({"title": "…"})
PATCH /api/tours/{id}writeMuuta otsikkoa, kuvausta, luokkaa, sijaintia, tunnisteita, slug-arvoa (luettava osoite), näkymien järjestystä, aloitusnäkymää ja näkymien nimiä
POST /api/tours/{id}/sceneswriteLataa 360°-kuva sellaisenaan pyynnön runkona
POST /api/content/{id}/visibilitywriteJulkaise kierros tai projekti, jaa se vain linkillä tai suojaa se salasanalla
GET /api/projectsreadListaa tilin projektit (limit, cursor, profileId)
GET /api/projects/{id}readYksi projekti kierroksineen, kuvineen, videoineen ja pohjapiirroksineen
GET /api/stats/{contentId}statsKierroksen tai projektin katselukerrat (range päivinä)
GET /api/stats/{contentId}/export.csvstatsSamat 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 tai null, jolloin kansikuvana käytetään aloitusnäkymää;
  • scenes: objekti, jonka avaimina ovat näkymätunnisteet ja jossa on name, view ({"yaw", "pitch", "fov"}) ja north (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/tiff tai image/webp;
  • x-file-name: tiedostonimi URL-koodattuna (encodeURIComponent); näkymä nimetään sen mukaan, joten 01-living-room.jpg saa nimen ”01 living room”;
  • x-pw-upload-batch ja x-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; category vaaditaan (aseta se ensin PATCH-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ä password pois, 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"]}}
TapahtumaMilloinTiedot
scene.readyNä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.sharpenedTäyden resoluution tiilet ovat paikallaanstage: "refine", ok (false, kun vaihe jätettiin pois ja näkymä jää esikatselulaatuun), pending
scene.vr_readyVR-tekstuurit ovat paikallaanstage: "vr", ok, pending
scene.failedKäsittely epäonnistui lopullisestierror ja syy
ping”Lähetä testi” -painiketyhjä

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

TilaKoodiMerkitys
400invalid_requestKenttä puuttuu tai on virheellinen; field kertoo, mikä
400unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_contentLatauksen tai julkaisun ennakkoehdot (projektissa on oltava julkinen kierros, kuva tai video)
401unauthorized, invalid_api_keyAvain puuttuu kokonaan, tai avain on virheellinen tai peruttu
402plan_required, quota_exceededPaketista puuttuu ominaisuus, tai raja on täynnä (feature tai limit kertoo, mikä)
403api_key_forbidden, api_scope_missingPäätepiste ei ole avainten käytettävissä, tai avaimelta puuttuu käyttöoikeus
404not_foundEi sinun, poistettu tai tunnistetta ei ole olemassa
409revision_conflict, slug_taken, in_password_projectSamanaikainen muokkaus (nykyinen kierros on mukana), osoite on jo käytössä, projektin salasanasääntö
413file_too_largeKokoraja ylittyy
429rate_limitedLiian monta pyyntöä; odota Retry-After sekuntia
503maintenancePrewalkia 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 koodit project_needs_public_tour ja project_needs_tour, joita ei enää lähetetä. GET /api/projects lisää kentän videoCount.
  • 22.10.2026: scene.ready sisältää pending-kentän; uudet tapahtumat scene.sharpened ja scene.vr_ready; latausjärjestyksen otsakkeet x-pw-upload-batch ja x-pw-upload-index; avaimella kutsuttuna GET /api/me kuvaa vain avaimen tilin.

Kysyttävää tai puuttuuko jokin päätepiste? Kirjoita osoitteeseen hello@prewalk.co.

Jaa: Jaa X:ssä LinkedIn WhatsApp

  • Mikä on 360°-kuva?

    Mikä on 360°-kuva? Se näyttää yhdestä pisteestä joka suunnan (360° × 180°) kuvasuhteessa 2:1. Näin otat ja katselet sen ja näin se eroaa panoraamasta.