API-reference

Prewalks API er en del af abonnementet Enterprise. Med en API-nøgle kan din egen software oprette fremvisninger, uploade scener, udgive, læse projekter og statistik og modtage en signeret webhook ved hvert behandlingstrin. Denne side er referencen; studiet og den offentlige afspiller fungerer som hidtil.

Basis-URL og konventioner

• Basis-URL: https://prewalk.co. Brug ikke app.prewalk.co: Den omdirigerer (308), og de fleste HTTP-klienter dropper Authorization-headeren ved en omdirigering til en anden vært.
• Format: JSON ind og ud (Content-Type: application/json), undtagen ved upload af scener, hvor billedet sendes som den rå request body.
• Id’er består af 12 små bogstaver og cifre, for eksempel teeg8crtm0u0. Datoer er ISO 8601 i UTC.
• Fejl ser altid ens ud: en HTTP-status og {"error": {"code": "…", "message": "…"}}; valideringsfejl tilføjer field. Koderne er listet sidst på denne side.
• Rate limit: 600 requests i minuttet pr. nøgle. Over grænsen får du 429 med en Retry-After-header (sekunder).

Godkendelse

Opret en nøgle under Indstillinger → API (kontoens ejer eller administrator, Enterprise). En nøgle hører til kontoen, kan begrænses til én brandprofil og har op til tre rettigheder: read, write og stats. Den fulde nøgle vises én gang; listen viser kun dens præfiks. Op til 20 nøgler pr. konto; en tilbagekaldt nøgle holder op med at virke med det samme.

Authorization: Bearer pw_…

En nøgle handler på vegne af én konto. GET /api/me beskriver hvad nøglen kan se: kontoen og dens abonnementsgrænser, kontoens profiler, den profil nøglen handler som (actor) og selve nøglen med dens rettigheder. Den returnerer aldrig nøgleejerens e-mailadresse eller vedkommendes andre konti.

Endpoints

Metode og sti	Rettighed	Hvad den gør
GET /api/me	read	Nøglens konto, profiler og rettigheder
GET /api/tours	read	List kontoens fremvisninger (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}	read	Én fremvisning med dens scener, hotspots og indstillinger
GET /api/tours/{id}/events	read	Behandlingsforløb som en server-sent event-strøm
POST /api/tours	write	Opret en fremvisning ({"title": "…"})
PATCH /api/tours/{id}	write	Skift titel, beskrivelse, kategori, sted, tags, slug (den læsbare adresse), scenernes rækkefølge, startscene, scenenavne
POST /api/tours/{id}/scenes	write	Upload et 360°-billede som rå body
POST /api/content/{id}/visibility	write	Udgiv, gør kun tilgængelig via link, eller beskyt en fremvisning eller et projekt med adgangskode
GET /api/projects	read	List kontoens projekter (limit, cursor, profileId)
GET /api/projects/{id}	read	Ét projekt med dets fremvisninger, billeder, videoer og plantegninger
GET /api/stats/{contentId}	stats	Visninger af en fremvisning eller et projekt (range i dage)
GET /api/stats/{contentId}/export.csv	stats	Det samme som CSV (table = daily, scenes eller referrers)

Alle andre endpoints svarer 403 api_key_forbidden ved kald med en nøgle. Konto, team, fakturering, API-nøgler og webhooks administreres i browseren.

Fremvisninger

List. GET /api/tours?limit=50 returnerer {"items": […], "next": "…", "usage": {…}}. Send next tilbage som cursor for at få næste side; usage indeholder kontoens antal scener og grænser. Hvert element har id, title, visibility, publishedAt, createdAt, updatedAt, profilen og antallet af scener.

Læs. GET /api/tours/{id} returnerer hele fremvisningen: title, description, category, location, tags, slug, visibility (public, link eller password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes i rækkefølge, hotspots, settings, audio og links (player er adressen der kan deles, post den offentlige side når fremvisningen er udgivet).

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 billedets midte, stigende mod højre) og, mens den behandles, stage og pct. En færdig scene har meta med sine tile-niveauer og medieroden.

Opret. POST /api/tours med {"title": "Harbor View — Unit 4"} returnerer den nye fremvisning. Uden en titel hedder den »Fremvisning uden titel«.

Opdatér. PATCH /api/tours/{id} tager et vilkårligt af disse felter og returnerer fremvisningen:

• title, description, category, location, tags (array af strenge), slug (den offentlige adresse; små bogstaver, cifre og bindestreger), commentsEnabled;
• order: et array af scene-id’er i den rækkefølge du ønsker; scener du udelader, beholder deres plads efter dem du har listet;
• startScene: et scene-id; scenen flyttes forrest (den første scene er startscenen);
• coverScene: et scene-id eller null for startscenen;
• scenes: et objekt med scene-id’er som nøgler og name, view ({"yaw", "pitch", "fov"}) og north (grader).

Send If-Match: "<revision>" med den revision du sidst læste, for at afvise en skrivning oven i en andens ændring: Svaret er så 409 revision_conflict med den aktuelle fremvisning i error.tour. Uden If-Match vinder den sidste der skriver.

Upload af scener

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

• Content-Type: image/jpeg, image/png, image/tiff eller image/webp;
• x-file-name: filnavnet, URL-kodet (encodeURIComponent); scenen får navn efter det, så 01-living-room.jpg bliver til »01 living room«;
• x-pw-upload-batch og x-pw-upload-index (valgfri): Når du uploader flere filer fra samme udvalg parallelt, så giv dem det samme batch-id (bogstaver, cifre, - og _, op til 32 tegn) og deres indeks i udvalget; serveren bevarer så den rækkefølge, uanset hvilken fil der bliver færdig først. Uden dem tilføjes scenerne i den rækkefølge de ankommer.

Accepterede billeder: ækvirektangulære 2:1-panoramaer op til abonnementets bredde (8K med Gratis, 16K med Pro og højere abonnementer) eller 1:1 top-bottom-stereopanoramaer med Pro og højere abonnementer (venstre øje øverst), op til 1 GiB. Svaret er scenen (status: "queued"). Behandlingen foregår i trin: Scenen bliver først synlig (preview-tiles), derefter kommer tiles i fuld opløsning (»skærpning«) og, med Pro og højere abonnementer, VR-teksturerne; de to kører side om side, og hvilken som helst af dem kan blive færdig først. Scenens meta.pending, event-strømmen og webhooks fortæller dig hvilke trin der stadig kører.

Fejl: 400 unsupported_format (ikke JPG, PNG, TIFF eller WebP), 400 unsupported_ratio (ikke 2:1 eller 1:1 top-bottom), 400 unreadable_image (en beskadiget fil), 402 plan_required (16K eller stereo med et abonnement uden det), 402 quota_exceeded (kontoens grænse for scener), 413 file_too_large.

Behandlingsforløb

GET /api/tours/{id}/events er en server-sent event-strøm (text/event-stream). Events: hello ved forbindelse, queue (køpladsen for ventende scener og et resumé af fremvisningen, hvert par sekunder mens noget kører), scene (status, stage, pct eller error) og tour (fremvisningen er ændret; læs den igen). Til integration mellem servere bør du foretrække webhooks nedenfor.

Udgivelse og synlighed

POST /api/content/{id}/visibility virker for fremvisninger og projekter og returnerer indholdet:

• {"visibility": "link"} – kan kun nås via sin adresse (standard for hver ny fremvisning);
• {"visibility": "public", "rightsAccepted": true} – på profilen, i Udforsk og indekserbar; en category er påkrævet (sæt den først med PATCH), og du bekræfter at du har ret til at udgive billederne. For et projekt tilføjer du "tourIds": [...] for at udgive fremvisninger sammen med det;
• {"visibility": "password", "password": "…"} – fra Pro; udelad password for at beholde den nuværende.

En fremvisning i et adgangskodebeskyttet projekt kan ikke gøres offentlig eller få sin egen adgangskode (409 in_password_project); det er projektets adgangskode der giver adgang.

Projekter

Projekter kan i dag kun læses via API’et. GET /api/projects lister dem med id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount og datoer; GET /api/projects/{id} tilføjer description, location, tags, urls (public og det private link), tours med deres scener samt galleriets images, videos og floorplans med markører. Opret projekter og tilføj medier i studiet.

Statistik

GET /api/stats/{contentId}?range=30 returnerer visninger for en fremvisning eller et projekt. Hvad du får, afhænger af abonnementet: det samlede total for hele perioden med Gratis; en nuludfyldt daily-serie (from, to, op til 90 dage) med Pro; op til 365 dage plus sources (side, indlejring, direkte), devices (mobil, computer, VR-briller), scenes og de indlejrende referrers med Office og Enterprise. …/export.csv?range=30&table=daily giver den daglige tabel, table=scenes visningerne pr. scene og table=referrers de sider der indlejrer. Visninger tælles pr. besøgendes adresse og indhold, én gang hvert 30. minut; intet personligt gemmes.

Webhooks

Tilføj op til fem webhooks under Indstillinger → API. Vi sender en signeret 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"]}}

Event	Hvornår	Data
scene.ready	Scenen er synlig (preview-tiles)	pending: trin der stadig kører – refine (tiles i fuld opløsning) og vr (teksturer til VR-briller); [] når forhåndsvisningen er endelig
scene.sharpened	Tiles i fuld opløsning er på plads	stage: "refine", ok (false når trinnet blev droppet og scenen forbliver i preview-kvalitet), pending
scene.vr_ready	VR-teksturerne er på plads	stage: "vr", ok, pending
scene.failed	Behandlingen mislykkedes endegyldigt	error med årsagen
ping	Knappen »Send test«	tom

Headers: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, hvor h1 er HMAC-SHA256 af ts + ":" + body med din webhook-hemmelighed (beregnet over præcis de bytes du har modtaget), plus Prewalk-Event-Id og Prewalk-Event-Type. Mens en udskiftning af hemmeligheden er i gang, har headeren to h1-værdier (ts=…;h1=<new>;h1=<old>), indtil den tidligere hemmelighed udløber: Acceptér leveringen når en af dem kan verificeres. Verificér signaturen, afvis et tidsstempel der er ældre end nogle få minutter, og fjern dubletter efter eventId: En levering forsøges igen indtil dit endpoint svarer 2xx (ti forsøg, 30 s og derefter fordobling, cirka fire timer i alt), og den gentagne body er byte for byte identisk. Efter 20 mislykkede leveringer i træk slås webhooken fra, og kontoens ejer får en e-mail. Endpoints skal være https på en offentlig adresse; omdirigeringer følges ikke. Hemmeligheden kan udskiftes; den tidligere forbliver gyldig i 24 timer.

Et gennemgået eksempel

# 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"

Indlejring

Indlejring kræver ingen nøgle: Hver fremvisning har https://prewalk.co/embed/{id}, og embed.js tilpasser rammens størrelse og åbner den i fuld skærm på din side. Hvilke hjemmesider der må vise dine indlejringer, indstilles under Indstillinger → Branding. Guiden til indlejring har detaljerne.

Fejlkoder

Status	Kode	Betydning
400	invalid_request	Et felt mangler eller er ugyldigt; field angiver hvilket
400	unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content	Forudsætninger for upload eller udgivelse (et projekt skal have en offentlig fremvisning, et billede eller en video)
401	unauthorized, invalid_api_key	Ingen nøgle overhovedet, eller en forkert formateret eller tilbagekaldt nøgle
402	plan_required, quota_exceeded	Abonnementet mangler funktionen, eller en grænse er nået (feature eller limit angiver hvilken)
403	api_key_forbidden, api_scope_missing	Endpointet er ikke åbent for nøgler, eller nøglen mangler rettigheden
404	not_found	Ikke din, slettet eller intet sådant id
409	revision_conflict, slug_taken, in_password_project	Samtidig redigering (den aktuelle fremvisning er med), adressen er i brug, regel for projektadgangskode
413	file_too_large	Over størrelsesgrænsen
429	rate_limited	For mange requests; vent Retry-After sekunder
503	maintenance	Prewalk opdateres; prøv igen om et minut

Ændringer

• 10. nov. 2026: et projekt kan udgives eller beskyttes med adgangskode med kun billeder eller videoer. Et projekt uden noget at vise svarer 400 project_needs_content, både offentligt og med adgangskode; koden erstatter project_needs_public_tour og project_needs_tour, som ikke længere sendes. GET /api/projects tilføjer videoCount.
• 22. okt. 2026: scene.ready har pending; nye events scene.sharpened og scene.vr_ready; headers til uploadrækkefølge x-pw-upload-batch og x-pw-upload-index; GET /api/me med en nøgle beskriver kun nøglens konto.

Spørgsmål eller mangler du et endpoint? Skriv til hello@prewalk.co.