API-referens

Prewalks API ingår i Enterprise-paketet. Med en API-nyckel kan din egen programvara skapa visningar, ladda upp scener, publicera, läsa projekt och statistik och få en signerad webhook i varje bearbetningssteg. Den här sidan är referensen; studion och den offentliga spelaren fungerar som tidigare.

Bas-URL och konventioner

• Bas-URL: https://prewalk.co. Använd inte app.prewalk.co: den omdirigerar (308) och de flesta HTTP-klienter tar bort Authorization-headern vid en omdirigering till en annan värd.
• Format: JSON in och ut (Content-Type: application/json), utom vid uppladdning av scener, där bilden skickas som rå body i anropet.
• ID:n består av 12 gemena bokstäver och siffror, till exempel teeg8crtm0u0. Datum anges i ISO 8601 i UTC.
• Fel ser alltid likadana ut: en HTTP-status och {"error": {"code": "…", "message": "…"}}; valideringsfel lägger till field. Koderna listas i slutet av den här sidan.
• Anropsgräns: 600 anrop per minut och nyckel. Över gränsen får du 429 med en Retry-After-header (sekunder).

Autentisering

Skapa en nyckel under Inställningar → API (kontots ägare eller administratör, Enterprise). En nyckel hör till kontot, kan begränsas till en varumärkesprofil och har upp till tre behörigheter: read, write och stats. Hela nyckeln visas en gång; listan visar bara dess prefix. Upp till 20 nycklar per konto; en återkallad nyckel slutar fungera direkt.

Authorization: Bearer pw_…

En nyckel agerar för ett konto. GET /api/me beskriver vad nyckeln kan se: kontot och paketets gränser, kontots profiler, den profil som nyckeln agerar som (actor) och själva nyckeln med dess behörigheter. Den returnerar aldrig e-postadressen till nyckelns ägare eller ägarens andra konton.

Endpoints

Metod och sökväg	Behörighet	Vad den gör
GET /api/me	read	Nyckelns konto, profiler och behörigheter
GET /api/tours	read	Listar kontots visningar (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}	read	En visning med dess scener, hotspots och inställningar
GET /api/tours/{id}/events	read	Bearbetningsförloppet som en ström av server-sent events
POST /api/tours	write	Skapar en visning ({"title": "…"})
PATCH /api/tours/{id}	write	Ändrar titel, beskrivning, kategori, plats, taggar, slug (den läsbara adressen), scenordning, startscen och scennamn
POST /api/tours/{id}/scenes	write	Laddar upp en 360°-bild som rå body
POST /api/content/{id}/visibility	write	Publicerar, gör endast tillgänglig via länk eller lösenordsskyddar en visning eller ett projekt
GET /api/projects	read	Listar kontots projekt (limit, cursor, profileId)
GET /api/projects/{id}	read	Ett projekt med dess visningar, bilder, videor och planritningar
GET /api/stats/{contentId}	stats	Besök på en visning eller ett projekt (range i dagar)
GET /api/stats/{contentId}/export.csv	stats	Samma sak som CSV (table = daily, scenes eller referrers)

Alla andra endpoints svarar 403 api_key_forbidden vid anrop med en nyckel. Konto, team, fakturering, API-nycklar och webhooks hanteras i webbläsaren.

Visningar

Lista. GET /api/tours?limit=50 returnerar {"items": […], "next": "…", "usage": {…}}. Skicka tillbaka next som cursor för att hämta nästa sida; usage innehåller kontots antal scener och gränser. Varje post har id, title, visibility, publishedAt, createdAt, updatedAt, profilen och antalet scener.

Läs. GET /api/tours/{id} returnerar hela visningen: title, description, category, location, tags, slug, visibility (public, link eller password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes i ordning, hotspots, settings, audio och links (player är adressen som kan delas, post den offentliga sidan när visningen är publicerad).

En scen har id, name, status (queued, processing, ready eller error), createdAt, eventuellt view (startriktningen: yaw, pitch och fov i radianer), north (radianer; 0 är bildens mitt och värdet ökar åt höger) och, medan scenen bearbetas, stage och pct. En färdig scen har meta med sina tile-nivåer och mediaroten.

Skapa. POST /api/tours med {"title": "Harbor View — Unit 4"} returnerar den nya visningen. Utan titel får den namnet ”Namnlös visning”.

Uppdatera. PATCH /api/tours/{id} tar emot vilka som helst av de här fälten och returnerar visningen:

• title, description, category, location, tags (array med strängar), slug (den offentliga adressen; gemena bokstäver, siffror och bindestreck), commentsEnabled;
• order: en array med scen-id:n i den ordning du vill ha dem; scener som du utelämnar behåller sin plats efter dem du listade;
• startScene: ett scen-id; scenen flyttas till början (den första scenen är startscenen);
• coverScene: ett scen-id, eller null för startscenen;
• scenes: ett objekt med scen-id:n som nycklar, med name, view ({"yaw", "pitch", "fov"}) och north (grader).

Skicka If-Match: "<revision>" med den revision som du senast läste för att avvisa en skrivning ovanpå någon annans ändring: svaret blir då 409 revision_conflict med den aktuella visningen i error.tour. Utan If-Match vinner den som skriver sist.

Ladda upp scener

POST /api/tours/{id}/scenes med bildfilen som rå body. Headers:

• Content-Type: image/jpeg, image/png, image/tiff eller image/webp;
• x-file-name: filnamnet, URL-kodat (encodeURIComponent); scenen får sitt namn efter det, så 01-living-room.jpg blir ”01 living room”;
• x-pw-upload-batch och x-pw-upload-index (valfria): när du laddar upp flera filer från ett och samma urval parallellt ger du dem samma batch-id (bokstäver, siffror, - och _, upp till 32 tecken) och deras index i urvalet; servern behåller då den ordningen oavsett vilken fil som blir klar först. Utan dem läggs scenerna till i den ordning de kommer in.

Godkända bilder: ekvirektangulära 2:1-panoramor upp till paketets bredd (8K i Gratis, 16K från Pro), eller 1:1-stereopanoramor i top-bottom-format från Pro (vänster öga överst), upp till 1 GiB. Svaret är scenen (status: "queued"). Bearbetningen sker i steg: först blir scenen synlig (tiles för förhandsvisning), sedan kommer tiles i full upplösning (”skärpning”) och, från Pro, VR-texturerna; de två körs parallellt och vilken som helst kan bli klar först. Scenens meta.pending, händelseströmmen och webhooks talar om vilka steg som fortfarande körs.

Fel: 400 unsupported_format (inte JPG, PNG, TIFF eller WebP), 400 unsupported_ratio (inte 2:1 eller 1:1 top-bottom), 400 unreadable_image (en skadad fil), 402 plan_required (16K eller stereo i ett paket som inte har det), 402 quota_exceeded (kontots scengräns), 413 file_too_large.

Bearbetningsförlopp

GET /api/tours/{id}/events är en ström av server-sent events (text/event-stream). Händelser: hello vid anslutning, queue (köplatsen för väntande scener och en sammanfattning av visningen, med några sekunders mellanrum medan något körs), scene (status, stage, pct eller error) och tour (visningen har ändrats; läs den igen). För integration mellan servrar är webhooks nedan att föredra.

Publicering och synlighet

POST /api/content/{id}/visibility fungerar för visningar och projekt och returnerar innehållet:

• {"visibility": "link"} – nås endast via sin adress (standard för varje ny visning);
• {"visibility": "public", "rightsAccepted": true} – på profilen, i Utforska och indexerbar; en category krävs (ange den först med PATCH) och du bekräftar att du har rätt att publicera bilderna. För ett projekt lägger du till "tourIds": [...] för att publicera visningar tillsammans med det;
• {"visibility": "password", "password": "…"} – från Pro; utelämna password för att behålla det nuvarande.

En visning i ett lösenordsskyddat projekt kan inte bli offentlig eller få ett eget lösenord (409 in_password_project); projektets lösenord är spärren.

Projekt

Projekt kan i dag bara läsas via API:et. GET /api/projects listar dem med id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount och datum; GET /api/projects/{id} lägger till description, location, tags, urls (public och den privata länken), tours med deras scener samt galleriets images, videos och floorplans med nålar. Skapa projekt och lägg till media i studion.

Statistik

GET /api/stats/{contentId}?range=30 returnerar besök på en visning eller ett projekt. Vad du får beror på paketet: totalsiffran för all tid, total, i paketet Gratis; en nollfylld daily-serie (from, to, upp till 90 dagar) i Pro-paketet; upp till 365 dagar plus sources (sida, inbäddning, direkt), devices (mobil, dator, VR-glasögon), scenes och de inbäddande referrers i paketen Office och Enterprise. …/export.csv?range=30&table=daily ger den dagliga tabellen, table=scenes besöken per scen och table=referrers de inbäddande webbplatserna. Besök räknas per besökares adress och innehåll, en gång var 30:e minut; inga personuppgifter sparas.

Webhooks

Lägg till upp till fem webhooks under Inställningar → API. Vi skickar en signerad POST med en JSON-body:

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

Händelse	När	Data
scene.ready	Scenen är synlig (tiles för förhandsvisning)	pending: steg som fortfarande körs – refine (tiles i full upplösning) och vr (texturer för VR-glasögon); [] när förhandsvisningen är slutgiltig
scene.sharpened	Tiles i full upplösning är på plats	stage: "refine", ok (false när steget hoppades över och scenen stannar på förhandsvisningskvalitet), pending
scene.vr_ready	VR-texturerna är på plats	stage: "vr", ok, pending
scene.failed	Bearbetningen misslyckades slutgiltigt	error med orsaken
ping	Knappen ”Skicka test”	tom

Headers: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, där h1 är HMAC-SHA256 av ts + ":" + body med din webhook-hemlighet (beräknad på exakt de byte som du tog emot), plus Prewalk-Event-Id och Prewalk-Event-Type. Medan en hemlighet byts ut innehåller headern två h1-värden (ts=…;h1=<new>;h1=<old>) tills den tidigare hemligheten upphör att gälla: godkänn leveransen när något av dem verifieras. Verifiera signaturen, avvisa en tidsstämpel som är äldre än några minuter och deduplicera på eventId: en leverans görs om tills din endpoint svarar 2xx (tio försök, 30 s och sedan dubbelt så länge varje gång, sammanlagt cirka fyra timmar) och den nya bodyn är byte för byte identisk. Efter 20 misslyckade leveranser i rad stängs webhooken av och kontots ägare får ett mejl. Endpoints måste använda https på en offentlig adress; omdirigeringar följs inte. Hemligheten kan bytas ut; den tidigare gäller i 24 timmar till.

Ett exempel steg för steg

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

# 2. upload two scenes in order
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. set a category and publish
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. views of the last 30 days
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"

Inbäddning

Inbäddning kräver ingen nyckel: varje visning har https://prewalk.co/embed/{id}, och embed.js anpassar ramens storlek och öppnar den i helskärm på din sida. Vilka webbplatser som får visa dina inbäddningar ställer du in under Inställningar → Varumärke. I guiden om inbäddning finns detaljerna.

Felkoder

Status	Kod	Betydelse
400	invalid_request	Ett fält saknas eller är ogiltigt; field anger vilket
400	unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content	Villkor för uppladdning eller publicering (ett projekt behöver en offentlig visning, en bild eller en video)
401	unauthorized, invalid_api_key	Ingen nyckel alls, eller en felformaterad eller återkallad nyckel
402	plan_required, quota_exceeded	Paketet saknar funktionen, eller en gräns är nådd (feature eller limit anger vilken)
403	api_key_forbidden, api_scope_missing	Endpointen är inte öppen för nycklar, eller nyckeln saknar behörigheten
404	not_found	Inte din, borttagen eller inget sådant id
409	revision_conflict, slug_taken, in_password_project	Samtidig ändring (den aktuella visningen ingår), adressen används redan, regeln för projektlösenord
413	file_too_large	Över storleksgränsen
429	rate_limited	För många anrop; vänta Retry-After sekunder
503	maintenance	Prewalk uppdateras; försök igen om en minut

Ändringar

• 10 nov. 2026: ett projekt kan publiceras eller lösenordsskyddas med bara bilder eller videor. Ett projekt utan något att visa svarar 400 project_needs_content, både offentligt och med lösenord; koden ersätter project_needs_public_tour och project_needs_tour, som inte längre skickas. GET /api/projects lägger till videoCount.
• 22 okt. 2026: scene.ready innehåller pending; nya händelser scene.sharpened och scene.vr_ready; headers för uppladdningsordning x-pw-upload-batch och x-pw-upload-index; GET /api/me med en nyckel beskriver bara nyckelns konto.

Frågor, eller saknar du en endpoint? Skriv till hello@prewalk.co.