API-referanse

22. okt. 202610 min lesetid

Prewalk-API-et er en del av Enterprise-planen. Med en API-nøkkel kan din egen programvare opprette omvisninger, laste opp scener, publisere, lese prosjekter og statistikk og få en signert webhook i hvert behandlingstrinn. Denne siden er referansen; studioet og den offentlige spilleren fungerer som før.

Basis-URL og konvensjoner

Basis-URL: https://prewalk.co. Ikke bruk app.prewalk.co: den videresender (308), og de fleste HTTP-klienter dropper Authorization-headeren ved videresending til en annen vert.
Format: JSON inn og ut (Content-Type: application/json), unntatt ved opplasting av scener, der bildet sendes som rå forespørselskropp.
ID-er består av 12 små bokstaver og sifre, for eksempel teeg8crtm0u0. Datoer er ISO 8601 i UTC.
Feil ser alltid like ut: en HTTP-status og {"error": {"code": "…", "message": "…"}}; valideringsfeil legger til field. Kodene står nederst på denne siden.
Hastighetsgrense: 600 forespørsler i minuttet per nøkkel. Over grensen får du 429 med en Retry-After-header (sekunder).

Autentisering

Opprett en nøkkel under Innstillinger → API (kontoeier eller administrator, Enterprise). En nøkkel tilhører kontoen, kan begrenses til én merkevareprofil og har opptil tre tilganger: read, write og stats. Hele nøkkelen vises bare én gang; listen viser bare prefikset. Opptil 20 nøkler per konto; en tilbakekalt nøkkel slutter å virke med en gang.

Authorization: Bearer pw_…

En nøkkel handler på vegne av én konto. GET /api/me beskriver hva nøkkelen kan se: kontoen og plangrensene, profilene i kontoen, profilen nøkkelen opptrer som (actor) og selve nøkkelen med tilgangene sine. Den returnerer aldri e-postadressen til nøkkeleieren eller de andre kontoene til eieren.

Endepunkter

Metode og sti	Tilgang	Hva det gjør
`GET /api/me`	read	Kontoen, profilene og tilgangene til nøkkelen
`GET /api/tours`	read	Lister opp omvisningene i kontoen (`limit` ≤ 50, `cursor`, `profileId`)
`GET /api/tours/{id}`	read	Én omvisning med scener, hotspoter og innstillinger
`GET /api/tours/{id}/events`	read	Behandlingsfremdrift som en strøm av server-sent events
`POST /api/tours`	write	Oppretter en omvisning (`{"title": "…"}`)
`PATCH /api/tours/{id}`	write	Endrer tittel, beskrivelse, kategori, sted, stikkord, `slug` (den lesbare adressen), scenerekkefølge, startscene og scenenavn
`POST /api/tours/{id}/scenes`	write	Laster opp et 360°-bilde som rå forespørselskropp
`POST /api/content/{id}/visibility`	write	Publiserer, gjør tilgjengelig kun via lenke eller passordbeskytter en omvisning eller et prosjekt
`GET /api/projects`	read	Lister opp prosjektene i kontoen (`limit`, `cursor`, `profileId`)
`GET /api/projects/{id}`	read	Ett prosjekt med omvisninger, bilder, videoer og plantegninger
`GET /api/stats/{contentId}`	stats	Visninger av en omvisning eller et prosjekt (`range` i dager)
`GET /api/stats/{contentId}/export.csv`	stats	Det samme som CSV (`table` = `daily`, `scenes` eller `referrers`)

Alle andre endepunkter svarer 403 api_key_forbidden når du bruker en nøkkel. Konto, team, fakturering, API-nøkler og webhooker administreres i nettleseren.

Omvisninger

Liste. GET /api/tours?limit=50 returnerer {"items": […], "next": "…", "usage": {…}}. Send next tilbake som cursor for å få neste side; usage inneholder antall scener i kontoen og grensene. Hvert element har id, title, visibility, publishedAt, createdAt, updatedAt, profilen og antall scener.

Lese. GET /api/tours/{id} returnerer hele omvisningen: title, description, category, location, tags, slug, visibility (public, link eller password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes i rekkefølge, hotspots, settings, audio og links (player er adressen som kan deles, post den offentlige siden når omvisningen er publisert).

En scene har id, name, status (queued, processing, ready eller error), createdAt, eventuelt view (startretningen: yaw, pitch og fov i radianer), north (radianer; 0 er midten av bildet, økende mot høyre), og mens den behandles, stage og pct. En ferdig scene har meta med flisnivåene og medieroten.

Opprette. POST /api/tours med {"title": "Harbor View — Unit 4"} returnerer den nye omvisningen. Uten tittel får den navnet «Omvisning uten navn».

Oppdatere. PATCH /api/tours/{id} tar imot hvilke som helst av disse feltene og returnerer omvisningen:

title, description, category, location, tags (en matrise med strenger), slug (den offentlige adressen, små bokstaver, sifre og bindestreker), commentsEnabled;
order: en matrise med scene-ID-er i den rekkefølgen du vil ha; scener du utelater, beholder plassen sin etter dem du listet opp;
startScene: en scene-ID; scenen flyttes fremst (den første scenen er startscenen);
coverScene: en scene-ID, eller null for startscenen;
scenes: et objekt med scene-ID-er som nøkler, med name, view ({"yaw", "pitch", "fov"}) og north (grader).

Send If-Match: "<revision>" med den revision du sist leste, for å hindre at du overskriver en annens endring: svaret blir da 409 revision_conflict med den gjeldende omvisningen i error.tour. Uten If-Match vinner den som skriver sist.

Opplasting av scener

POST /api/tours/{id}/scenes med bildefilen som rå forespørselskropp. Headere:

Content-Type: image/jpeg, image/png, image/tiff eller image/webp;
x-file-name: filnavnet, URL-kodet (encodeURIComponent); scenen får navn etter det, så 01-living-room.jpg blir «01 living room»;
x-pw-upload-batch og x-pw-upload-index (valgfritt): når du laster opp flere filer fra ett utvalg parallelt, gir du dem samme batch-ID (bokstaver, sifre, - og _, opptil 32 tegn) og indeksen deres i utvalget; serveren beholder da den rekkefølgen uansett hvilken fil som blir ferdig først. Uten dem legges scenene til i den rekkefølgen de kommer inn.

Godtatte bilder: ekvirektangulære 2:1-panoramaer opptil bredden planen tillater (8K på gratisplanen, 16K fra Pro og oppover), eller 1:1 topp-bunn-stereopanoramaer fra Pro og oppover (venstre øye øverst), opptil 1 GiB. Svaret er scenen (status: "queued"). Behandlingen skjer i trinn: Scenen blir først synlig (forhåndsvisningsfliser), deretter kommer flisene i full oppløsning («skjerping») og, fra Pro og oppover, VR-teksturene; de to trinnene kjører side om side, og hvilket som helst av dem kan bli ferdig først. Scenens meta.pending, hendelsesstrømmen og webhookene forteller deg hvilke trinn som fortsatt kjører.

Feil: 400 unsupported_format (ikke JPG, PNG, TIFF eller WebP), 400 unsupported_ratio (ikke 2:1 eller 1:1 topp-bunn), 400 unreadable_image (en skadet fil), 402 plan_required (16K eller stereo på en plan uten dette), 402 quota_exceeded (scenegrensen for kontoen), 413 file_too_large.

Behandlingsfremdrift

GET /api/tours/{id}/events er en strøm av server-sent events (text/event-stream). Hendelser: hello ved tilkobling, queue (køplassen til ventende scener og et sammendrag av omvisningen, med noen sekunders mellomrom mens noe kjører), scene (status, stage, pct eller error) og tour (omvisningen er endret; les den på nytt). For integrasjon mellom servere bør du heller bruke webhookene nedenfor.

Publisering og synlighet

POST /api/content/{id}/visibility fungerer for omvisninger og prosjekter og returnerer innholdet:

{"visibility": "link"} – kan bare nås via adressen (standard for alle nye omvisninger);
{"visibility": "public", "rightsAccepted": true} – på profilen, i Utforsk og kan indekseres; en category er påkrevd (angi den med PATCH først), og du bekrefter at du har rett til å publisere bildene. For et prosjekt legger du til "tourIds": [...] for å publisere omvisninger sammen med det;
{"visibility": "password", "password": "…"} – fra Pro og oppover; utelat password for å beholde det nåværende.

En omvisning i et passordbeskyttet prosjekt kan ikke gjøres offentlig eller få et eget passord (409 in_password_project); det er prosjektets passord som styrer tilgangen.

Prosjekter

Prosjekter kan foreløpig bare leses via API-et. GET /api/projects lister dem opp med id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount og datoer; GET /api/projects/{id} legger til description, location, tags, urls (public og den private lenken), tours med scenene sine, og galleriets images, videos og floorplans med markører. Opprett prosjekter og legg til medier i studioet.

Statistikk

GET /api/stats/{contentId}?range=30 returnerer visninger for en omvisning eller et prosjekt. Hva du får, avhenger av planen: totalen for hele perioden, total, på gratisplanen; en nullfylt daily-serie (from, to, opptil 90 dager) på Pro-planen; opptil 365 dager pluss sources (side, innbygging, direkte), devices (mobil, datamaskin, VR-briller), scenes og referrers (nettstedene som bygger inn innholdet) på Office- og Enterprise-planen. …/export.csv?range=30&table=daily gir den daglige tabellen, table=scenes visningene per scene og table=referrers nettstedene som bygger inn innholdet. Visninger telles per besøkendes adresse og innhold, én gang hvert 30. minutt; ingenting personlig lagres.

Webhooker

Legg til opptil fem webhooker under Innstillinger → API. Vi sender en signert POST med en JSON-kropp:

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

Hendelse	Når	Data
`scene.ready`	Scenen er synlig (forhåndsvisningsfliser)	`pending`: trinn som fortsatt kjører – `refine` (fliser i full oppløsning) og `vr` (teksturer for VR-briller); `[]` når forhåndsvisningen er endelig
`scene.sharpened`	Flisene i full oppløsning er på plass	`stage: "refine"`, `ok` (false når trinnet ble droppet og scenen blir værende i forhåndsvisningskvalitet), `pending`
`scene.vr_ready`	VR-teksturene er på plass	`stage: "vr"`, `ok`, `pending`
`scene.failed`	Behandlingen mislyktes for godt	`error` med årsaken
`ping`	Knappen «Send test»	tom

Headere: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, der h1 er HMAC-SHA256 av ts + ":" + body med webhook-hemmeligheten din (beregnet over nøyaktig de bytene du mottok), pluss Prewalk-Event-Id og Prewalk-Event-Type. Mens en rotasjon av hemmeligheten pågår, har headeren to h1-verdier (ts=…;h1=<new>;h1=<old>) til den forrige hemmeligheten utløper: Godta leveransen når en av dem kan verifiseres. Verifiser signaturen, avvis et tidsstempel som er eldre enn noen minutter, og fjern duplikater ut fra eventId: En leveranse forsøkes på nytt til endepunktet ditt svarer 2xx (ti forsøk, først etter 30 s og deretter med dobbelt så lang ventetid hver gang, omtrent fire timer totalt), og kroppen i nye forsøk er identisk byte for byte. Etter 20 mislykkede leveranser på rad slås webhooken av, og kontoeieren får en e-post. Endepunkter må bruke https på en offentlig adresse; videresendinger følges ikke. Hemmeligheten kan roteres; den forrige forblir gyldig i 24 timer.

Steg for steg

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

# 2. last opp to scener i rekkefølge
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. angi en kategori og publiser
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. visninger de siste 30 dagene
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"

Innbygging

Innbygging krever ingen nøkkel: Hver omvisning har https://prewalk.co/embed/{id}, og embed.js tilpasser størrelsen på rammen og åpner den i fullskjerm på siden din. Hvilke nettsteder som kan vise innbyggingene dine, angir du under Innstillinger → Merkevare. Guiden om innbygging har detaljene.

Feilkoder

Status	Kode	Betydning
400	`invalid_request`	Et felt mangler eller er ugyldig; `field` angir hvilket
400	`unsupported_format`, `unsupported_ratio`, `unreadable_image`, `rights_required`, `category_required`, `project_needs_content`	Forutsetninger for opplasting eller publisering (et prosjekt trenger en offentlig omvisning, et bilde eller en video)
401	`unauthorized`, `invalid_api_key`	Ingen nøkkel i det hele tatt, eller en feilformatert eller tilbakekalt nøkkel
402	`plan_required`, `quota_exceeded`	Planen mangler funksjonen, eller en grense er nådd (`feature` eller `limit` angir hvilken)
403	`api_key_forbidden`, `api_scope_missing`	Endepunktet er ikke åpent for nøkler, eller nøkkelen mangler tilgangen
404	`not_found`	Ikke din, slettet eller ingen slik ID
409	`revision_conflict`, `slug_taken`, `in_password_project`	Samtidig redigering (den gjeldende omvisningen følger med), adressen er i bruk, passordregelen for prosjektet
413	`file_too_large`	Over størrelsesgrensen
429	`rate_limited`	For mange forespørsler; vent i `Retry-After` sekunder
503	`maintenance`	Prewalk oppdateres; prøv igjen om et minutt

Endringer

10. nov. 2026: et prosjekt kan publiseres eller passordbeskyttes med bare bilder eller videoer. Et prosjekt uten noe å vise svarer 400 project_needs_content, både offentlig og med passord; koden erstatter project_needs_public_tour og project_needs_tour, som ikke lenger sendes. GET /api/projects legger til videoCount.
22. okt. 2026: scene.ready har pending; nye hendelser scene.sharpened og scene.vr_ready; headere for opplastingsrekkefølge, x-pw-upload-batch og x-pw-upload-index; GET /api/me med en nøkkel beskriver bare kontoen til nøkkelen.

Har du spørsmål, eller mangler du et endepunkt? Skriv til hello@prewalk.co.

Del: 𝕏 LinkedIn WhatsApp

API-referanse

Basis-URL og konvensjoner

Autentisering

Endepunkter

Omvisninger

Opplasting av scener

Behandlingsfremdrift

Publisering og synlighet

Prosjekter

Statistikk

Webhooker

Steg for steg

Innbygging

Feilkoder

Endringer

Slik lager du en virtuell visning med 360°-bilder

Din første omvisning på 10 minutter

Slik fotograferer du en bolig med et 360°-kamera

Basis-URL og konvensjoner

Autentisering

Endepunkter

Omvisninger

Opplasting av scener

Behandlingsfremdrift

Publisering og synlighet

Prosjekter

Statistikk

Webhooker

Steg for steg

Innbygging

Feilkoder

Endringer

Mer fra Guider

Slik lager du en virtuell visning med 360°-bilder

Din første omvisning på 10 minutter

Slik fotograferer du en bolig med et 360°-kamera

Informasjonskapsler