Referensi API
API Prewalk adalah bagian dari paket Enterprise. Dengan kunci API, perangkat lunak Anda sendiri dapat membuat tur, mengunggah adegan, memublikasikan, membaca proyek dan statistik, serta menerima webhook bertanda tangan di setiap tahap pemrosesan. Halaman ini adalah referensinya; studio dan pemutar publik tetap berfungsi seperti sebelumnya.
URL dasar dan konvensi
- URL dasar:
https://prewalk.co. Jangan gunakanapp.prewalk.co: alamat itu melakukan pengalihan (308), dan sebagian besar klien HTTP membuang headerAuthorizationsaat dialihkan ke host lain. - Format: JSON untuk masukan dan keluaran (
Content-Type: application/json), kecuali unggahan adegan, yang mengirim gambar sebagai isi permintaan mentah. - ID terdiri atas 12 huruf kecil dan angka, misalnya
teeg8crtm0u0. Tanggal memakai format ISO 8601 dalam UTC. - Kesalahan selalu berbentuk sama: status HTTP dan
{"error": {"code": "…", "message": "…"}}; kesalahan validasi menambahkanfield. Daftar kodenya ada di akhir halaman ini. - Batas laju: 600 permintaan per menit per kunci. Jika melebihinya, Anda menerima
429dengan headerRetry-After(dalam detik).
Autentikasi
Buat kunci di Pengaturan → API (pemilik akun atau admin, Enterprise). Sebuah kunci milik akun, dapat dibatasi ke satu profil merek, dan memiliki hingga tiga cakupan: read, write, dan stats. Kunci lengkap hanya ditampilkan sekali; daftar hanya menampilkan awalannya. Maksimal 20 kunci per akun; kunci yang dicabut langsung berhenti berfungsi.
Authorization: Bearer pw_…
Sebuah kunci bertindak untuk satu akun. GET /api/me menjelaskan apa yang dapat dilihat kunci tersebut: akun beserta batas paketnya, profil-profil akun itu, profil tempat kunci bertindak (actor), dan kunci itu sendiri beserta cakupannya. Endpoint ini tidak pernah mengembalikan email pemilik kunci atau akun-akun lain miliknya.
Endpoint
| Metode dan path | Cakupan | Fungsi |
|---|---|---|
GET /api/me | read | Akun, profil, dan cakupan kunci |
GET /api/tours | read | Menampilkan daftar tur akun (limit ≤ 50, cursor, profileId) |
GET /api/tours/{id} | read | Satu tur beserta adegan, hotspot, dan pengaturannya |
GET /api/tours/{id}/events | read | Progres pemrosesan sebagai aliran server-sent event |
POST /api/tours | write | Membuat tur ({"title": "…"}) |
PATCH /api/tours/{id} | write | Mengubah judul, deskripsi, kategori, lokasi, tag, slug (alamat yang mudah dibaca), urutan adegan, adegan awal, nama adegan |
POST /api/tours/{id}/scenes | write | Mengunggah gambar 360° sebagai isi mentah |
POST /api/content/{id}/visibility | write | Memublikasikan tur atau proyek, menjadikannya hanya dengan tautan, atau melindunginya dengan kata sandi |
GET /api/projects | read | Menampilkan daftar proyek akun (limit, cursor, profileId) |
GET /api/projects/{id} | read | Satu proyek beserta tur, gambar, video, dan denahnya |
GET /api/stats/{contentId} | stats | Tayangan sebuah tur atau proyek (range dalam hari) |
GET /api/stats/{contentId}/export.csv | stats | Data yang sama dalam CSV (table = daily, scenes, atau referrers) |
Semua endpoint lain menjawab 403 api_key_forbidden jika dipanggil dengan kunci. Akun, tim, penagihan, kunci API, dan webhook dikelola di browser.
Tur
Daftar. GET /api/tours?limit=50 mengembalikan {"items": […], "next": "…", "usage": {…}}. Kirim kembali next sebagai cursor untuk halaman berikutnya; usage berisi jumlah adegan dan batas akun. Setiap item memiliki id, title, visibility, publishedAt, createdAt, updatedAt, profil, dan jumlah adegan.
Baca. GET /api/tours/{id} mengembalikan tur lengkap: title, description, category, location, tags, slug, visibility (public, link, atau password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, scenes sesuai urutan, hotspots, settings, audio, dan links (player adalah alamat yang dapat dibagikan, post adalah halaman publik setelah dipublikasikan).
Sebuah adegan memiliki id, name, status (queued, processing, ready, atau error), createdAt, secara opsional view (arah tampilan awal: yaw, pitch, dan fov dalam radian), north (radian; 0 adalah bagian tengah gambar, bertambah ke kanan), serta stage dan pct selama sedang diproses. Adegan yang sudah siap membawa meta berisi level tile dan root media-nya.
Buat. POST /api/tours dengan {"title": "Harbor View — Unit 4"} mengembalikan tur baru. Tanpa judul, tur diberi nama “Tur tanpa judul”.
Perbarui. PATCH /api/tours/{id} menerima kolom mana pun berikut ini dan mengembalikan tur:
title,description,category,location,tags(array string),slug(alamat publik, berupa huruf kecil, angka, dan tanda hubung),commentsEnabled;order: array ID adegan sesuai urutan yang Anda inginkan; adegan yang tidak Anda cantumkan tetap berada setelah adegan yang Anda cantumkan;startScene: ID adegan; adegan ini dipindahkan ke depan (adegan pertama adalah adegan awal);coverScene: ID adegan, ataunulluntuk adegan awal;scenes: objek dengan ID adegan sebagai kunci, berisiname,view({"yaw", "pitch", "fov"}), dannorth(derajat).
Kirim If-Match: "<revision>" dengan revision yang terakhir Anda baca agar penulisan di atas perubahan orang lain ditolak: jawabannya kemudian 409 revision_conflict dengan tur terkini di error.tour. Tanpa If-Match, penulisan terakhir yang berlaku.
Mengunggah adegan
POST /api/tours/{id}/scenes dengan file gambar sebagai isi mentah. Header:
Content-Type:image/jpeg,image/png,image/tiff, atauimage/webp;x-file-name: nama file, dalam bentuk URL-encoded (encodeURIComponent); adegan diberi nama sesuai nama file, sehingga01-living-room.jpgmenjadi “01 living room”;x-pw-upload-batchdanx-pw-upload-index(opsional): saat Anda mengunggah beberapa file dari satu pilihan secara paralel, beri semuanya ID batch yang sama (huruf, angka,-, dan_, hingga 32 karakter) serta indeksnya dalam pilihan; server kemudian mempertahankan urutan itu, file mana pun yang selesai lebih dulu. Tanpa header ini, adegan ditambahkan sesuai urutan kedatangan.
Gambar yang diterima: panorama equirectangular 2:1 hingga lebar maksimal paket (8K di Gratis, 16K di Pro ke atas), atau panorama stereo top-bottom 1:1 di Pro ke atas (mata kiri di atas), hingga 1 GiB. Jawabannya berupa adegan (status: "queued"). Pemrosesan berjalan dalam beberapa tahap: adegan tampil lebih dulu (tile pratinjau), lalu tile resolusi penuh menyusul (“penajaman”), begitu pula tekstur VR di Pro ke atas; keduanya berjalan berdampingan dan mana pun bisa selesai lebih dulu. meta.pending pada adegan, aliran event, dan webhook memberi tahu Anda tahap mana yang masih berjalan.
Kesalahan: 400 unsupported_format (bukan JPG, PNG, TIFF, atau WebP), 400 unsupported_ratio (bukan 2:1, atau 1:1 top-bottom), 400 unreadable_image (file rusak), 402 plan_required (16K atau stereo pada paket yang tidak menyediakannya), 402 quota_exceeded (batas adegan akun), 413 file_too_large.
Progres pemrosesan
GET /api/tours/{id}/events adalah aliran server-sent event (text/event-stream). Event: hello saat terhubung, queue (posisi antrean adegan yang menunggu dan ringkasan tur, setiap beberapa detik selama ada proses yang berjalan), scene (status, stage, pct, atau error), dan tour (tur berubah; baca ulang tur tersebut). Untuk integrasi antarserver, sebaiknya gunakan webhook di bawah ini.
Publikasi dan visibilitas
POST /api/content/{id}/visibility berlaku untuk tur dan proyek, dan mengembalikan kontennya:
{"visibility": "link"}: hanya dapat dibuka lewat alamatnya (bawaan setiap tur baru);{"visibility": "public", "rightsAccepted": true}: tampil di profil, di Jelajahi, dan dapat diindeks;categorywajib diisi (atur dulu denganPATCH), dan Anda menyatakan bahwa Anda berhak memublikasikan gambar-gambar tersebut. Untuk proyek, tambahkan"tourIds": [...]untuk memublikasikan tur bersama proyeknya;{"visibility": "password", "password": "…"}: Pro ke atas; hilangkanpassworduntuk mempertahankan kata sandi saat ini.
Tur di dalam proyek yang dilindungi kata sandi tidak bisa menjadi publik atau memiliki kata sandi sendiri (409 in_password_project); kata sandi proyeklah yang menjadi gerbangnya.
Proyek
Saat ini, proyek hanya dapat dibaca melalui API. GET /api/projects menampilkan daftarnya dengan id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount, dan tanggal; GET /api/projects/{id} menambahkan description, location, tags, urls (public dan tautan privat), tours beserta adegannya, serta images, videos, dan floorplans galeri beserta pin-nya. Buat proyek dan tambahkan media di studio.
Statistik
GET /api/stats/{contentId}?range=30 mengembalikan tayangan sebuah tur atau proyek. Data yang Anda dapatkan bergantung pada paket: total sepanjang waktu di Gratis; deret daily yang diisi nol (from, to, hingga 90 hari) di Pro; hingga 365 hari ditambah sources (halaman, sematan, langsung), devices (ponsel, desktop, headset VR), scenes, dan referrers penyemat di Office dan Enterprise. …/export.csv?range=30&table=daily memberikan tabel harian, table=scenes tayangan per adegan, dan table=referrers situs yang menyematkan. Tayangan dihitung per alamat pengunjung dan konten, sekali setiap 30 menit; tidak ada data pribadi yang disimpan.
Webhook
Tambahkan hingga lima webhook di Pengaturan → API. Kami mengirim POST bertanda tangan dengan isi JSON:
{"eventId": "evt_…", "eventType": "scene.ready", "occurredAt": "2026-10-22T09:12:03.000Z",
"data": {"tourId": "…", "sceneId": "…", "status": "ready", "pending": ["refine", "vr"]}}
| Event | Kapan | Data |
|---|---|---|
scene.ready | Adegan sudah tampil (tile pratinjau) | pending: tahap yang masih berjalan—refine (tile resolusi penuh) dan vr (tekstur headset); [] jika pratinjau sudah final |
scene.sharpened | Tile resolusi penuh sudah terpasang | stage: "refine", ok (false jika tahap ini dibatalkan dan adegan tetap pada kualitas pratinjau), pending |
scene.vr_ready | Tekstur VR sudah terpasang | stage: "vr", ok, pending |
scene.failed | Pemrosesan gagal secara permanen | error beserta alasannya |
ping | Tombol “Kirim tes” | kosong |
Header: Prewalk-Signature: ts=<unix seconds>;h1=<hex>, dengan h1 adalah HMAC-SHA256 dari ts + ":" + body menggunakan secret webhook Anda (dihitung atas byte persis yang Anda terima), ditambah Prewalk-Event-Id dan Prewalk-Event-Type. Selama rotasi secret berlangsung, header ini membawa dua nilai h1 (ts=…;h1=<new>;h1=<old>) sampai secret sebelumnya kedaluwarsa: terima pengiriman jika salah satunya lolos verifikasi. Verifikasi tanda tangan, tolak timestamp yang lebih lama dari beberapa menit, dan hapus duplikat berdasarkan eventId: pengiriman diulang sampai endpoint Anda menjawab 2xx (sepuluh percobaan, 30 detik lalu terus berlipat ganda, total sekitar empat jam), dan isi yang dikirim ulang identik hingga ke tingkat byte. Setelah 20 pengiriman gagal berturut-turut, webhook dinonaktifkan dan pemilik akun menerima email. Endpoint harus berupa https di alamat publik; pengalihan tidak diikuti. Secret dapat dirotasi; secret sebelumnya tetap berlaku selama 24 jam.
Contoh langkah demi langkah
# 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"
Penyematan
Penyematan tidak memerlukan kunci: setiap tur memiliki https://prewalk.co/embed/{id}, dan embed.js mengatur ukuran bingkai serta membukanya dalam layar penuh di halaman Anda. Situs web mana yang boleh menampilkan sematan Anda diatur di Pengaturan → Identitas merek. Panduan penyematan berisi detailnya.
Kode kesalahan
| Status | Kode | Arti |
|---|---|---|
| 400 | invalid_request | Sebuah kolom tidak ada atau tidak valid; field menyebutkan namanya |
| 400 | unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content | Prasyarat unggah atau publikasi (proyek memerlukan tur publik, gambar, atau video) |
| 401 | unauthorized, invalid_api_key | Tidak ada kunci sama sekali, atau kunci salah format atau sudah dicabut |
| 402 | plan_required, quota_exceeded | Paket tidak menyediakan fitur tersebut, atau batas telah tercapai (feature atau limit menyebutkan yang mana) |
| 403 | api_key_forbidden, api_scope_missing | Endpoint tidak terbuka untuk kunci, atau kunci tidak memiliki cakupan yang diperlukan |
| 404 | not_found | Bukan milik Anda, sudah dihapus, atau ID tidak ada |
| 409 | revision_conflict, slug_taken, in_password_project | Pengeditan bersamaan (tur terkini disertakan), alamat sudah dipakai, aturan kata sandi proyek |
| 413 | file_too_large | Melebihi batas ukuran |
| 429 | rate_limited | Terlalu banyak permintaan; tunggu Retry-After detik |
| 503 | maintenance | Prewalk sedang diperbarui; coba lagi setelah satu menit |
Perubahan
- 10 Nov 2026: proyek kini bisa dipublikasikan atau dilindungi kata sandi hanya dengan gambar atau video. Proyek yang tidak punya apa pun untuk ditampilkan menjawab
400 project_needs_content, baik publik maupun dengan kata sandi; kode ini menggantikanproject_needs_public_tourdanproject_needs_tour, yang tidak lagi dikirim.GET /api/projectsmenambahkanvideoCount. - 22 Okt 2026:
scene.readymembawapending; event baruscene.sharpeneddanscene.vr_ready; header urutan unggahx-pw-upload-batchdanx-pw-upload-index;GET /api/medengan kunci hanya menjelaskan akun milik kunci tersebut.
Ada pertanyaan atau endpoint yang belum tersedia? Tulis ke hello@prewalk.co.
Bagikan: Bagikan di X LinkedIn WhatsApp



