API-referentie

De Prewalk API hoort bij het Enterprise-pakket. Met een API-sleutel kan je eigen software tours maken, scènes uploaden, publiceren, projecten en statistieken lezen en bij elke verwerkingsstap een ondertekende webhook ontvangen. Deze pagina is de referentie; de studio en de openbare player blijven werken zoals voorheen.

Basis-URL en conventies

• Basis-URL: https://prewalk.co. Gebruik app.prewalk.co niet: dat stuurt door (308) en de meeste HTTP-clients laten de Authorization-header vallen bij een doorverwijzing naar een andere host.
• Formaat: JSON in en uit (Content-Type: application/json), behalve bij het uploaden van scènes, waarbij de afbeelding als ruwe request-body wordt verstuurd.
• ID’s bestaan uit 12 kleine letters en cijfers, bijvoorbeeld teeg8crtm0u0. Datums zijn ISO 8601 in UTC.
• Fouten zien er altijd hetzelfde uit: een HTTP-status en {"error": {"code": "…", "message": "…"}}; validatiefouten voegen field toe. De codes staan onderaan deze pagina.
• Rate limit: 600 requests per minuut per sleutel. Daarboven krijg je 429 met een Retry-After-header (seconden).

Authenticatie

Maak een sleutel aan in Instellingen → API (accounteigenaar of beheerder, Enterprise). Een sleutel hoort bij het account, kan worden beperkt tot één merkprofiel en heeft maximaal drie rechten: read, write en stats. De volledige sleutel wordt één keer getoond; de lijst toont alleen het voorvoegsel. Maximaal 20 sleutels per account; een ingetrokken sleutel werkt meteen niet meer.

Authorization: Bearer pw_…

Een sleutel handelt namens één account. GET /api/me beschrijft wat de sleutel kan zien: het account en de limieten van het pakket, de profielen van dat account, het profiel waarmee de sleutel optreedt (actor) en de sleutel zelf met zijn rechten. Het geeft nooit het e-mailadres van de eigenaar van de sleutel of diens andere accounts terug.

Endpoints

Methode en pad	Recht	Wat het doet
GET /api/me	read	Het account, de profielen en de rechten van de sleutel
GET /api/tours	read	De tours van het account opvragen (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}	read	Eén tour met zijn scènes, hotspots en instellingen
GET /api/tours/{id}/events	read	Verwerkingsvoortgang als server-sent event stream
POST /api/tours	write	Een tour maken ({"title": "…"})
PATCH /api/tours/{id}	write	Titel, beschrijving, categorie, locatie, tags, slug (het leesbare adres), scènevolgorde, startscène en scènenamen wijzigen
POST /api/tours/{id}/scenes	write	Een 360°-afbeelding als ruwe body uploaden
POST /api/content/{id}/visibility	write	Een tour of project publiceren, alleen via link beschikbaar maken of met een wachtwoord beveiligen
GET /api/projects	read	De projecten van het account opvragen (limit, cursor, profileId)
GET /api/projects/{id}	read	Eén project met zijn tours, afbeeldingen, video’s en plattegronden
GET /api/stats/{contentId}	stats	Weergaven van een tour of project (range in dagen)
GET /api/stats/{contentId}/export.csv	stats	Hetzelfde als CSV (table = daily, scenes of referrers)

Met een sleutel antwoorden alle andere endpoints met 403 api_key_forbidden. Account, team, facturering, API-sleutels en webhooks beheer je in de browser.

Tours

Opvragen. GET /api/tours?limit=50 geeft {"items": […], "next": "…", "usage": {…}} terug. Geef next terug als cursor voor de volgende pagina; usage bevat het aantal scènes en de limieten van het account. Elk item heeft id, title, visibility, publishedAt, createdAt, updatedAt, het profiel en het aantal scènes.

Lezen. GET /api/tours/{id} geeft de volledige tour terug: title, description, category, location, tags, slug, visibility (public, link of password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes op volgorde, hotspots, settings, audio en links (player is het deelbare adres, post de openbare pagina als de tour gepubliceerd is).

Een scène heeft id, name, status (queued, processing, ready of error), createdAt, optioneel view (de beginrichting: yaw, pitch en fov in radialen), north (radialen; 0 is het midden van de afbeelding, oplopend naar rechts) en, zolang hij wordt verwerkt, stage en pct. Een scène die klaar is, heeft meta met zijn tegelniveaus en de mediaroot.

Maken. POST /api/tours met {"title": "Harbor View — Unit 4"} geeft de nieuwe tour terug. Zonder titel heet hij “Naamloze tour”.

Bijwerken. PATCH /api/tours/{id} accepteert elk van deze velden en geeft de tour terug:

• title, description, category, location, tags (array van strings), slug (het openbare adres, kleine letters, cijfers en streepjes), commentsEnabled;
• order: een array van scène-id’s in de gewenste volgorde; scènes die je weglaat, houden hun plaats na de scènes die je hebt opgegeven;
• startScene: een scène-id; die scène wordt naar voren verplaatst (de eerste scène is de startscène);
• coverScene: een scène-id of null voor de startscène;
• scenes: een object met scène-id’s als sleutels, met name, view ({"yaw", "pitch", "fov"}) en north (graden).

Stuur If-Match: "<revision>" mee met de revision die je het laatst hebt gelezen om te voorkomen dat je over de wijziging van iemand anders heen schrijft: het antwoord is dan 409 revision_conflict met de huidige tour in error.tour. Zonder If-Match wint wie het laatst schrijft.

Scènes uploaden

POST /api/tours/{id}/scenes met het afbeeldingsbestand als ruwe body. Headers:

• Content-Type: image/jpeg, image/png, image/tiff of image/webp;
• x-file-name: de bestandsnaam, URL-gecodeerd (encodeURIComponent); de scène krijgt die naam, dus 01-living-room.jpg wordt “01 living room”;
• x-pw-upload-batch en x-pw-upload-index (optioneel): als je meerdere bestanden uit één selectie parallel uploadt, geef ze dan dezelfde batch-id (letters, cijfers, - en _, maximaal 32 tekens) en hun index in de selectie; de server houdt dan die volgorde aan, ongeacht welk bestand als eerste klaar is. Zonder deze headers worden scènes toegevoegd in de volgorde waarin ze binnenkomen.

Geaccepteerde afbeeldingen: 2:1 equirectangular panorama’s tot de breedte van het pakket (8K in het gratis pakket, 16K vanaf Pro), of 1:1 top-bottom stereopanorama’s vanaf Pro (linkeroog boven), tot 1 GiB. Het antwoord is de scène (status: "queued"). De verwerking verloopt in stappen: eerst wordt de scène zichtbaar (voorbeeldtegels), daarna komen de tegels in volledige resolutie (“verscherpen”) en vanaf Pro de VR-texturen; die twee lopen naast elkaar en elk van beide kan als eerste klaar zijn. De meta.pending van de scène, de event stream en de webhooks vertellen je welke stappen nog lopen.

Fouten: 400 unsupported_format (geen JPG, PNG, TIFF of WebP), 400 unsupported_ratio (niet 2:1, of 1:1 top-bottom), 400 unreadable_image (een beschadigd bestand), 402 plan_required (16K of stereo in een pakket zonder die functie), 402 quota_exceeded (de scènelimiet van het account), 413 file_too_large.

Verwerkingsvoortgang

GET /api/tours/{id}/events is een server-sent event stream (text/event-stream). Events: hello bij het verbinden, queue (de plaats in de wachtrij van wachtende scènes en een samenvatting van de tour, om de paar seconden zolang er iets loopt), scene (status, stage, pct of error) en tour (de tour is gewijzigd; lees hem opnieuw). Gebruik voor een koppeling tussen servers bij voorkeur de webhooks hieronder.

Publiceren en zichtbaarheid

POST /api/content/{id}/visibility werkt voor tours en projecten en geeft de content terug:

• {"visibility": "link"} – alleen bereikbaar via het adres (de standaard voor elke nieuwe tour);
• {"visibility": "public", "rightsAccepted": true} – op het profiel, in Ontdekken en indexeerbaar; een category is verplicht (stel die eerst in met PATCH) en je bevestigt dat je het recht hebt om de afbeeldingen te publiceren. Voeg voor een project "tourIds": [...] toe om tours tegelijk met het project te publiceren;
• {"visibility": "password", "password": "…"} – vanaf Pro; laat password weg om het huidige wachtwoord te houden.

Een tour in een project met een wachtwoord kan niet openbaar worden en geen eigen wachtwoord krijgen (409 in_password_project); het wachtwoord van het project bepaalt de toegang.

Projecten

Projecten zijn via de API voorlopig alleen te lezen. GET /api/projects geeft ze terug met id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount en datums; GET /api/projects/{id} voegt daar description, location, tags, urls (public en de privélink), de tours met hun scènes, en de galerij images, videos en floorplans met pins aan toe. Maak projecten en voeg media toe in de studio.

Statistieken

GET /api/stats/{contentId}?range=30 geeft de weergaven van een tour of project terug. Wat je krijgt, hangt af van het pakket: het totaal aller tijden total in het gratis pakket; een met nullen aangevulde reeks daily (from, to, tot 90 dagen) in het Pro-pakket; tot 365 dagen plus sources (pagina, insluiting, direct), devices (telefoon, desktop, VR-bril), scenes en de insluitende referrers in het Office- en Enterprise-pakket. …/export.csv?range=30&table=daily geeft de dagtabel, table=scenes de weergaven per scène en table=referrers de sites waarop de content is ingesloten. Weergaven worden geteld per bezoekersadres en content, eens per 30 minuten; er wordt niets persoonlijks opgeslagen.

Webhooks

Voeg maximaal vijf webhooks toe in Instellingen → API. We sturen een ondertekende POST met een JSON-body:

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

Event	Wanneer	Gegevens
scene.ready	De scène is zichtbaar (voorbeeldtegels)	pending: stappen die nog lopen – refine (tegels in volledige resolutie) en vr (texturen voor de VR-bril); [] als het voorbeeld definitief is
scene.sharpened	De tegels in volledige resolutie staan klaar	stage: "refine", ok (false als de stap is overgeslagen en de scène op voorbeeldkwaliteit blijft), pending
scene.vr_ready	De VR-texturen staan klaar	stage: "vr", ok, pending
scene.failed	De verwerking is definitief mislukt	error met de reden
ping	De knop “Test versturen”	leeg

Headers: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, waarbij h1 de HMAC-SHA256 is van ts + ":" + body met je webhookgeheim (berekend over precies de bytes die je hebt ontvangen), plus Prewalk-Event-Id en Prewalk-Event-Type. Tijdens het vervangen van een geheim bevat de header twee h1-waarden (ts=…;h1=<new>;h1=<old>) tot het vorige geheim verloopt: accepteer de levering als een van beide klopt. Controleer de handtekening, weiger een tijdstempel die ouder is dan een paar minuten en ontdubbel op eventId: een levering wordt opnieuw geprobeerd tot je endpoint met 2xx antwoordt (tien pogingen, eerst na 30 s en daarna steeds twee keer zo lang, in totaal ongeveer vier uur) en de body van een nieuwe poging is byte voor byte gelijk. Na 20 mislukte afleveringen op rij wordt de webhook uitgeschakeld en krijgt de accounteigenaar een e-mail. Endpoints moeten https zijn op een openbaar adres; doorverwijzingen worden niet gevolgd. Het geheim kan worden vervangen; het vorige blijft 24 uur geldig.

Een voorbeeld stap voor stap

# 1. maak een 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 twee scènes op volgorde
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. stel een categorie in en publiceer
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. weergaven van de afgelopen 30 dagen
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"

Insluiten

Voor insluiten heb je geen sleutel nodig: elke tour heeft https://prewalk.co/embed/{id}, en embed.js bepaalt de grootte van het frame en opent het schermvullend op je pagina. Welke websites je insluitingen mogen tonen, stel je in onder Instellingen → Huisstijl. In de gids over insluiten lees je de details.

Foutcodes

Status	Code	Betekenis
400	invalid_request	Een veld ontbreekt of is ongeldig; field noemt het
400	unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content	Voorwaarden voor uploaden of publiceren (een project heeft een openbare tour, een afbeelding of een video nodig)
401	unauthorized, invalid_api_key	Helemaal geen sleutel, of een ongeldige of ingetrokken sleutel
402	plan_required, quota_exceeded	Het pakket heeft de functie niet, of een limiet is bereikt (feature of limit zegt welke)
403	api_key_forbidden, api_scope_missing	Het endpoint is niet open voor sleutels, of de sleutel mist het recht
404	not_found	Niet van jou, verwijderd of een onbekende id
409	revision_conflict, slug_taken, in_password_project	Gelijktijdige bewerking (de huidige tour wordt meegestuurd), adres al in gebruik, wachtwoordregel van het project
413	file_too_large	Boven de maximale bestandsgrootte
429	rate_limited	Te veel requests; wacht Retry-After seconden
503	maintenance	Prewalk wordt bijgewerkt; probeer het na een minuut opnieuw

Wijzigingen

• 10 nov 2026: een project kan ook met alleen afbeeldingen of video’s worden gepubliceerd of met een wachtwoord worden beveiligd. Een project zonder iets om te tonen antwoordt 400 project_needs_content, zowel openbaar als met wachtwoord; die code vervangt project_needs_public_tour en project_needs_tour, die niet meer worden verstuurd. GET /api/projects voegt videoCount toe.
• 22 okt 2026: scene.ready bevat pending; nieuwe events scene.sharpened en scene.vr_ready; headers voor de uploadvolgorde x-pw-upload-batch en x-pw-upload-index; GET /api/me met een sleutel beschrijft alleen het account van de sleutel.

Vragen of mis je een endpoint? Schrijf naar hello@prewalk.co.