Zum Inhalt springen
← Zurück zum Ratgeber

API-Referenz

11 Min. Lesezeit

Die Prewalk-API ist Teil des individuellen Tarifs. Mit einem API-Schlüssel kann Ihre eigene Software Rundgänge erstellen, Szenen hochladen, veröffentlichen, Projekte und Statistiken lesen und zu jeder Verarbeitungsstufe einen signierten Webhook erhalten. Diese Seite ist die Referenz; das Studio und der öffentliche Player funktionieren weiter wie bisher.

Basis-URL und Konventionen

  • Basis-URL: https://prewalk.co. Verwenden Sie nicht app.prewalk.co: Diese Adresse leitet weiter (308), und die meisten HTTP-Clients verwerfen den Header Authorization bei einer Weiterleitung auf einen anderen Host.
  • Format: JSON in beide Richtungen (Content-Type: application/json), außer bei Szenen-Uploads, die das Bild als rohen Request-Body senden.
  • IDs bestehen aus 12 Kleinbuchstaben und Ziffern, zum Beispiel teeg8crtm0u0. Datumsangaben sind ISO 8601 in UTC.
  • Fehler sehen immer gleich aus: ein HTTP-Status und {"error": {"code": "…", "message": "…"}}; Validierungsfehler ergänzen field. Die Codes stehen am Ende dieser Seite.
  • Ratenlimit: 600 Anfragen pro Minute und Schlüssel. Darüber erhalten Sie 429 mit einem Header Retry-After (Sekunden).

Authentifizierung

Erstellen Sie einen Schlüssel unter Einstellungen → API (Kontoinhaber oder Administrator, Tarif Individuell). Ein Schlüssel gehört zum Konto, kann auf ein Markenprofil beschränkt werden und hat bis zu drei Scopes: read, write und stats. Der vollständige Schlüssel wird einmal angezeigt; die Liste zeigt nur sein Präfix. Bis zu 20 Schlüssel pro Konto; ein widerrufener Schlüssel funktioniert sofort nicht mehr.

Authorization: Bearer pw_…

Ein Schlüssel handelt für ein Konto. GET /api/me beschreibt, was der Schlüssel sehen kann: das Konto und seine Tarif-Limits, die Profile dieses Kontos, das Profil, als das der Schlüssel handelt (actor), und den Schlüssel selbst mit seinen Scopes. Die E-Mail-Adresse des Schlüsselinhabers oder dessen andere Konten gibt der Endpunkt nie zurück.

Endpunkte

Methode und PfadScopeFunktion
GET /api/mereadKonto, Profile und Scopes des Schlüssels
GET /api/toursreadRundgänge des Kontos auflisten (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}readEin Rundgang mit Szenen, Hotspots und Einstellungen
GET /api/tours/{id}/eventsreadVerarbeitungsfortschritt als Server-Sent-Events-Stream
POST /api/tourswriteRundgang erstellen ({"title": "…"})
PATCH /api/tours/{id}writeTitel, Beschreibung, Kategorie, Standort, Tags, slug (die lesbare Adresse), Szenenreihenfolge, Startszene, Szenennamen ändern
POST /api/tours/{id}/sceneswriteEin 360°-Bild als rohen Body hochladen
POST /api/content/{id}/visibilitywriteEinen Rundgang oder ein Projekt veröffentlichen, auf „nur über Link“ setzen oder mit Passwort schützen
GET /api/projectsreadProjekte des Kontos auflisten (limit, cursor, profileId)
GET /api/projects/{id}readEin Projekt mit Rundgängen, Bildern, Videos und Grundrissen
GET /api/stats/{contentId}statsAufrufe eines Rundgangs oder Projekts (range in Tagen)
GET /api/stats/{contentId}/export.csvstatsDasselbe als CSV (table = daily, scenes oder referrers)

Jeder andere Endpunkt antwortet bei Zugriff mit einem Schlüssel mit 403 api_key_forbidden. Konto, Team, Abrechnung, API-Schlüssel und Webhooks werden im Browser verwaltet.

Rundgänge

Auflisten. GET /api/tours?limit=50 gibt {"items": […], "next": "…", "usage": {…}} zurück. Übergeben Sie next als cursor, um die nächste Seite zu erhalten; usage enthält die Szenenanzahl und die Limits des Kontos. Jedes Element hat id, title, visibility, publishedAt, createdAt, updatedAt, das Profil und die Szenenanzahl.

Lesen. GET /api/tours/{id} gibt den vollständigen Rundgang zurück: title, description, category, location, tags, slug, visibility (public, link oder password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes in ihrer Reihenfolge, hotspots, settings, audio und links (player ist die teilbare Adresse, post die öffentliche Seite, sobald der Rundgang veröffentlicht ist).

Eine Szene hat id, name, status (queued, processing, ready oder error), createdAt, optional view (die Startansicht: yaw, pitch und fov im Bogenmaß), north (im Bogenmaß; 0 ist die Bildmitte, nach rechts zunehmend) und während der Verarbeitung stage und pct. Eine fertige Szene enthält meta mit ihren Kachelstufen und dem Medienstammverzeichnis.

Erstellen. POST /api/tours mit {"title": "Harbor View — Unit 4"} gibt den neuen Rundgang zurück. Ohne Titel heißt er „Untitled tour“.

Aktualisieren. PATCH /api/tours/{id} akzeptiert beliebige der folgenden Felder und gibt den Rundgang zurück:

  • title, description, category, location, tags (Array von Strings), slug (die öffentliche Adresse aus Kleinbuchstaben, Ziffern und Bindestrichen), commentsEnabled;
  • order: ein Array von Szenen-IDs in der gewünschten Reihenfolge; nicht aufgeführte Szenen behalten ihren Platz hinter den aufgeführten;
  • startScene: eine Szenen-ID; die Szene wird nach vorne verschoben (die erste Szene ist die Startszene);
  • coverScene: eine Szenen-ID oder null für die Startszene;
  • scenes: ein Objekt mit Szenen-IDs als Schlüsseln, jeweils mit name, view ({"yaw", "pitch", "fov"}) und north (in Grad).

Senden Sie If-Match: "<revision>" mit der zuletzt gelesenen revision, damit ein Schreibvorgang über die Änderung einer anderen Person abgelehnt wird: Die Antwort ist dann 409 revision_conflict mit dem aktuellen Rundgang in error.tour. Ohne If-Match gewinnt, wer zuletzt schreibt.

Szenen hochladen

POST /api/tours/{id}/scenes mit der Bilddatei als rohem Body. Header:

  • Content-Type: image/jpeg, image/png, image/tiff oder image/webp;
  • x-file-name: der Dateiname, URL-kodiert (encodeURIComponent); die Szene wird danach benannt, aus 01-living-room.jpg wird also „01 living room“;
  • x-pw-upload-batch und x-pw-upload-index (optional): Wenn Sie mehrere Dateien einer Auswahl parallel hochladen, geben Sie ihnen dieselbe Batch-ID (Buchstaben, Ziffern, - und _, bis zu 32 Zeichen) und ihren Index in der Auswahl; der Server behält dann diese Reihenfolge bei, egal welche Datei zuerst fertig ist. Ohne diese Header werden Szenen in der Reihenfolge ihres Eintreffens angehängt.

Akzeptierte Bilder: äquirektanguläre 2:1-Panoramen bis zur Breite des Tarifs (8K im kostenlosen Tarif, 16K ab Pro) oder ab Pro 1:1-Top-Bottom-Stereopanoramen (linkes Auge oben), bis 1 GiB. Die Antwort ist die Szene (status: "queued"). Die Verarbeitung läuft in Stufen: Zuerst wird die Szene sichtbar (Vorschaukacheln), dann kommen die Kacheln in voller Auflösung („Schärfen“) und ab Pro die VR-Texturen; beide laufen parallel, und jede von ihnen kann zuerst fertig werden. meta.pending der Szene, der Event-Stream und die Webhooks zeigen, welche Stufen noch laufen.

Fehler: 400 unsupported_format (kein JPG, PNG, TIFF oder WebP), 400 unsupported_ratio (nicht 2:1 bzw. nicht 1:1 Top-Bottom), 400 unreadable_image (eine beschädigte Datei), 402 plan_required (16K oder Stereo in einem Tarif ohne diese Funktion), 402 quota_exceeded (das Szenenlimit des Kontos), 413 file_too_large.

Verarbeitungsfortschritt

GET /api/tours/{id}/events ist ein Server-Sent-Events-Stream (text/event-stream). Events: hello beim Verbindungsaufbau, queue (die Warteschlangenposition wartender Szenen und eine Zusammenfassung des Rundgangs, alle paar Sekunden, solange etwas läuft), scene (status, stage, pct oder error) und tour (der Rundgang hat sich geändert; lesen Sie ihn erneut). Für Server-zu-Server-Integrationen sind die Webhooks unten die bessere Wahl.

Veröffentlichen und Sichtbarkeit

POST /api/content/{id}/visibility funktioniert für Rundgänge und Projekte und gibt den Inhalt zurück:

  • {"visibility": "link"} – nur über die Adresse erreichbar (die Voreinstellung jedes neuen Rundgangs);
  • {"visibility": "public", "rightsAccepted": true} – im Profil, in Entdecken und indexierbar; eine category ist erforderlich (setzen Sie sie zuvor mit PATCH), und Sie bestätigen, dass Sie das Recht haben, die Bilder zu veröffentlichen. Für ein Projekt fügen Sie "tourIds": [...] hinzu, um Rundgänge zusammen mit dem Projekt zu veröffentlichen;
  • {"visibility": "password", "password": "…"} – ab Pro; lassen Sie password weg, um das aktuelle Passwort beizubehalten.

Ein Rundgang in einem passwortgeschützten Projekt kann weder öffentlich werden noch ein eigenes Passwort erhalten (409 in_password_project); den Zugang regelt das Passwort des Projekts.

Projekte

Projekte sind über die API derzeit nur lesbar. GET /api/projects listet sie mit id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount und Datumsangaben auf; GET /api/projects/{id} ergänzt description, location, tags, urls (public und den privaten Link), die tours mit ihren Szenen sowie aus der Galerie images, videos und floorplans mit Pins. Erstellen Sie Projekte und fügen Sie Medien im Studio hinzu.

Statistiken

GET /api/stats/{contentId}?range=30 gibt die Aufrufe eines Rundgangs oder Projekts zurück. Was Sie erhalten, hängt vom Tarif ab: im kostenlosen Tarif den Gesamtwert total seit Beginn; im Pro-Tarif eine mit Nullen aufgefüllte Tagesreihe daily (from, to, bis zu 90 Tage); in Office und Individuell bis zu 365 Tage plus sources (Seite, Einbettung, direkt), devices (Handy, Desktop, VR-Brille), scenes und die einbettenden referrers. …/export.csv?range=30&table=daily liefert die Tagestabelle, table=scenes die Aufrufe pro Szene und table=referrers die einbettenden Websites. Aufrufe werden pro Besucheradresse und Inhalt gezählt, einmal alle 30 Minuten; es werden keine personenbezogenen Daten gespeichert.

Webhooks

Fügen Sie unter Einstellungen → API bis zu fünf Webhooks hinzu. Wir senden einen signierten POST mit einem JSON-Body:

{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
 "data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}
EventZeitpunktDaten
scene.readyDie Szene ist sichtbar (Vorschaukacheln)pending: noch laufende Stufen – refine (Kacheln in voller Auflösung) und vr (Texturen für VR-Brillen); [], wenn die Vorschau endgültig ist
scene.sharpenedDie Kacheln in voller Auflösung sind bereitstage: "refine", ok (false, wenn die Stufe verworfen wurde und die Szene in Vorschauqualität bleibt), pending
scene.vr_readyDie VR-Texturen sind bereitstage: "vr", ok, pending
scene.failedDie Verarbeitung ist endgültig fehlgeschlagenerror mit dem Grund
pingDie Schaltfläche „Test senden“leer

Header: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, wobei h1 der HMAC-SHA256 von ts + ":" + body mit Ihrem Webhook-Secret ist (berechnet über genau die Bytes, die Sie empfangen haben), dazu Prewalk-Event-Id und Prewalk-Event-Type. Während eine Secret-Rotation läuft, enthält der Header zwei h1-Werte (ts=…;h1=<new>;h1=<old>), bis das vorherige Secret abläuft: Akzeptieren Sie die Zustellung, wenn einer davon gültig ist. Prüfen Sie die Signatur, lehnen Sie Zeitstempel ab, die älter als ein paar Minuten sind, und deduplizieren Sie anhand von eventId: Eine Zustellung wird wiederholt, bis Ihr Endpunkt mit 2xx antwortet (zehn Versuche, zuerst nach 30 s, dann jeweils doppelt so lange, insgesamt etwa vier Stunden), und der wiederholte Body ist byteidentisch. Nach 20 fehlgeschlagenen Zustellungen in Folge wird der Webhook deaktiviert, und der Kontoinhaber erhält eine E-Mail. Endpunkte müssen https auf einer öffentlichen Adresse verwenden; Weiterleitungen werden nicht verfolgt. Das Secret kann rotiert werden; das vorherige bleibt 24 Stunden gültig.

Ein Beispiel Schritt für Schritt

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

Einbetten

Zum Einbetten ist kein Schlüssel nötig: Jeder Rundgang hat https://prewalk.co/embed/{id}, und embed.js passt die Größe des Frames an und öffnet ihn auf Ihrer Seite im Vollbild. Welche Websites Ihre Einbettungen zeigen dürfen, legen Sie unter Einstellungen → Branding fest. Der Einbettungsratgeber enthält die Details.

Fehlercodes

StatusCodeBedeutung
400invalid_requestEin Feld fehlt oder ist ungültig; field nennt es
400unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_contentVoraussetzungen für Upload oder Veröffentlichung (ein Projekt braucht einen öffentlichen Rundgang, ein Bild oder ein Video)
401unauthorized, invalid_api_keyGar kein Schlüssel oder ein fehlerhafter oder widerrufener Schlüssel
402plan_required, quota_exceededDem Tarif fehlt die Funktion, oder ein Limit ist erreicht (feature oder limit gibt an, welches)
403api_key_forbidden, api_scope_missingDer Endpunkt ist für Schlüssel nicht freigegeben, oder dem Schlüssel fehlt der Scope
404not_foundNicht Ihres, gelöscht oder keine solche ID
409revision_conflict, slug_taken, in_password_projectGleichzeitige Bearbeitung (der aktuelle Rundgang ist enthalten), Adresse vergeben, Passwortregel des Projekts
413file_too_largeÜber dem Größenlimit
429rate_limitedZu viele Anfragen; warten Sie Retry-After Sekunden
503maintenancePrewalk wird aktualisiert; nach einer Minute erneut versuchen

Änderungen

  • 10. Nov. 2026: Ein Projekt lässt sich jetzt auch nur mit Bildern oder Videos veröffentlichen oder mit einem Passwort schützen. Ein Projekt, das nichts zu zeigen hat, antwortet mit 400 project_needs_content, öffentlich wie mit Passwort; dieser Code ersetzt project_needs_public_tour und project_needs_tour, die nicht mehr gesendet werden. GET /api/projects ergänzt videoCount.
  • 22. Okt. 2026: scene.ready enthält pending; neue Events scene.sharpened und scene.vr_ready; Header für die Upload-Reihenfolge x-pw-upload-batch und x-pw-upload-index; GET /api/me mit einem Schlüssel beschreibt nur das Konto des Schlüssels.

Fragen oder ein fehlender Endpunkt? Schreiben Sie an hello@prewalk.co.

Teilen: 𝕏 LinkedIn WhatsApp