API referansı

Prewalk API, Kurumsal paketin bir parçasıdır. Bir API anahtarıyla kendi yazılımın tur oluşturabilir, sahne yükleyebilir, yayımlayabilir, projeleri ve istatistikleri okuyabilir ve her işleme aşamasında imzalı bir webhook alabilir. Bu sayfa API referansıdır; stüdyo ve herkese açık oynatıcı eskisi gibi çalışmaya devam eder.

Temel URL ve kurallar

• Temel URL: https://prewalk.co. app.prewalk.co adresini kullanma: bu adres yönlendirme yapar (308) ve çoğu HTTP istemcisi başka bir alan adına yapılan yönlendirmede Authorization başlığını düşürür.
• Biçim: giriş ve çıkış JSON’dur (Content-Type: application/json); tek istisna, görseli ham istek gövdesi olarak gönderen sahne yüklemeleridir.
• Kimlikler (ID) 12 küçük harf ve rakamdan oluşur, örneğin teeg8crtm0u0. Tarihler UTC’de ISO 8601 biçimindedir.
• Hatalar her zaman aynı biçimdedir: bir HTTP durum kodu ve {"error": {"code": "…", "message": "…"}}; doğrulama hataları buna field ekler. Kodlar bu sayfanın sonunda listelenir.
• İstek sınırı: anahtar başına dakikada 600 istek. Sınırı aşarsan 429 yanıtı ve Retry-After başlığı (saniye) alırsın.

Kimlik doğrulama

Ayarlar → API bölümünde bir anahtar oluştur (hesap sahibi ya da yönetici, Kurumsal paket). Anahtar hesaba aittir, tek bir marka profiliyle sınırlandırılabilir ve en çok üç kapsamı olur: read, write ve stats. Anahtarın tamamı yalnız bir kez gösterilir; listede yalnız ön eki görünür. Hesap başına en çok 20 anahtar olabilir; iptal edilen bir anahtar anında çalışmayı bırakır.

Authorization: Bearer pw_…

Bir anahtar tek bir hesap adına işlem yapar. GET /api/me, anahtarın neleri görebildiğini açıklar: hesabı ve paket sınırlarını, o hesabın profillerini, anahtarın adına işlem yaptığı profili (actor) ve kapsamlarıyla birlikte anahtarın kendisini. Anahtar sahibinin e-posta adresini ya da diğer hesaplarını hiçbir zaman döndürmez.

Uç noktalar

Yöntem ve yol	Kapsam	Ne yapar
GET /api/me	read	Anahtarın hesabı, profilleri ve kapsamları
GET /api/tours	read	Hesabın turlarını listeler (limit ≤ 50, cursor, profileId)
GET /api/tours/{id}	read	Sahneleri, geçiş noktaları ve ayarlarıyla tek bir tur
GET /api/tours/{id}/events	read	İşleme ilerlemesi, server-sent events akışı olarak
POST /api/tours	write	Tur oluşturur ({"title": "…"})
PATCH /api/tours/{id}	write	Başlığı, açıklamayı, kategoriyi, konumu, etiketleri, slug değerini (okunabilir adres), sahne sırasını, başlangıç sahnesini ve sahne adlarını değiştirir
POST /api/tours/{id}/scenes	write	Ham gövde olarak bir 360° görsel yükler
POST /api/content/{id}/visibility	write	Bir turu ya da projeyi yayımlar, yalnız bağlantıyla paylaşıma alır ya da şifreyle korur
GET /api/projects	read	Hesabın projelerini listeler (limit, cursor, profileId)
GET /api/projects/{id}	read	Turları, görselleri, videoları ve kat planlarıyla tek bir proje
GET /api/stats/{contentId}	stats	Bir turun ya da projenin görüntülenmeleri (gün cinsinden range)
GET /api/stats/{contentId}/export.csv	stats	Aynı veriler CSV olarak (table = daily, scenes ya da referrers)

Diğer tüm uç noktalar, anahtarla çağrıldığında 403 api_key_forbidden yanıtı verir. Hesap, ekip, ödeme, API anahtarları ve webhook’lar tarayıcıdan yönetilir.

Turlar

Listeleme. GET /api/tours?limit=50, {"items": […], "next": "…", "usage": {…}} döndürür. Sonraki sayfa için next değerini cursor olarak geri gönder; usage, hesabın sahne sayısını ve sınırlarını içerir. Her öğede id, title, visibility, publishedAt, createdAt, updatedAt, profil ve sahne sayıları bulunur.

Okuma. GET /api/tours/{id} turun tamamını döndürür: title, description, category, location, tags, slug, visibility (public, link ya da password), hasPassword, publishedAt, profile, projectId, startScene, coverScene, revision, sıralı scenes, hotspots, settings, audio ve links (player paylaşılabilir adres, post yayımlandığında herkese açık sayfa).

Bir sahnede id, name, status (queued, processing, ready ya da error), createdAt, isteğe bağlı olarak view (açılış yönü: radyan cinsinden yaw, pitch ve fov), north (radyan; 0 görselin ortasıdır ve sağa doğru artar) ve sahne işlenirken stage ile pct bulunur. Hazır bir sahne, karo seviyelerini ve medya kök adresini içeren meta alanını taşır.

Oluşturma. POST /api/tours, {"title": "Harbor View — Unit 4"} ile yeni turu döndürür. Başlık vermezsen tur “Adsız tur” olarak görünür.

Güncelleme. PATCH /api/tours/{id} şu alanlardan herhangi birini alır ve turu döndürür:

• title, description, category, location, tags (metin dizisi), slug (herkese açık adres; küçük harf, rakam ve tire), commentsEnabled;
• order: istediğin sırada sahne kimliklerinden oluşan bir dizi; dışarıda bıraktığın sahneler, listelediklerinin ardından kendi sıralarını korur;
• startScene: bir sahne kimliği; sahne en başa taşınır (ilk sahne başlangıç sahnesidir);
• coverScene: bir sahne kimliği ya da başlangıç sahnesi için null;
• scenes: sahne kimliklerini anahtar olarak kullanan, name, view ({"yaw", "pitch", "fov"}) ve north (derece) içeren bir nesne.

Başkasının değişikliğinin üzerine yazmayı önlemek için en son okuduğun revision değeriyle If-Match: "<revision>" başlığını gönder: bu durumda yanıt, error.tour içinde güncel turla birlikte 409 revision_conflict olur. If-Match olmadan son yazan kazanır.

Sahne yükleme

POST /api/tours/{id}/scenes isteğinde görsel dosyası ham gövde olarak gönderilir. Başlıklar:

• Content-Type: image/jpeg, image/png, image/tiff ya da image/webp;
• x-file-name: URL kodlamalı dosya adı (encodeURIComponent); sahne adını buradan alır, yani 01-living-room.jpg “01 living room” olur;
• x-pw-upload-batch ve x-pw-upload-index (isteğe bağlı): tek bir seçimdeki birkaç dosyayı paralel yüklediğinde hepsine aynı grup kimliğini (harf, rakam, - ve _, en çok 32 karakter) ve seçimdeki sıra numaralarını ver; sunucu, hangi dosya önce biterse bitsin bu sırayı korur. Bunlar olmadan sahneler geliş sırasına göre eklenir.

Kabul edilen görseller: paketin genişlik sınırına kadar 2:1 panoramalar (Ücretsiz pakette 8K, Pro ve üstünde 16K) ya da Pro ve üstünde 1:1 üst-alt stereo panoramalar (sol göz üstte); dosya başına en çok 1 GiB. Yanıt sahnenin kendisidir (status: "queued"). İşleme aşamalar halinde ilerler: önce sahne görünür hale gelir (önizleme karoları), ardından tam çözünürlüklü karolar gelir (“netleşme”) ve Pro ve üstünde VR dokuları hazırlanır; bu ikisi yan yana çalışır ve hangisi önce biter, belli olmaz. Sahnenin meta.pending alanı, olay akışı ve webhook’lar hangi aşamaların hâlâ sürdüğünü bildirir.

Hatalar: 400 unsupported_format (JPG, PNG, TIFF ya da WebP değil), 400 unsupported_ratio (2:1 ya da 1:1 üst-alt değil), 400 unreadable_image (bozuk dosya), 402 plan_required (16K ya da stereo, bunları içermeyen bir pakette), 402 quota_exceeded (hesabın sahne sınırı), 413 file_too_large.

İşleme ilerlemesi

GET /api/tours/{id}/events bir server-sent events akışıdır (text/event-stream). Olaylar: bağlanınca hello, queue (bekleyen sahnelerin kuyruktaki sırası ve turun özeti; işleyen bir şey olduğu sürece birkaç saniyede bir), scene (status, stage, pct ya da error) ve tour (tur değişti; yeniden oku). Sunucudan sunucuya entegrasyon için aşağıdaki webhook’ları tercih et.

Yayımlama ve görünürlük

POST /api/content/{id}/visibility turlar ve projeler için çalışır ve içeriği döndürür:

• {"visibility": "link"} — yalnız adresiyle erişilebilir (her yeni turun varsayılanı);
• {"visibility": "public", "rightsAccepted": true} — profilde ve Keşfet’te görünür, dizine eklenebilir; bir category zorunludur (önce PATCH ile ayarla) ve görselleri yayımlama hakkın olduğunu onaylarsın. Bir projede, turları projeyle birlikte yayımlamak için "tourIds": [...] ekle;
• {"visibility": "password", "password": "…"} — Pro ve üstü; mevcut şifreyi korumak için password alanını gönderme.

Şifreli bir projenin içindeki bir tur herkese açık olamaz ve kendi şifresini alamaz (409 in_password_project); kapıyı projenin şifresi tutar.

Projeler

Projeler bugün API üzerinden yalnız okunabilir. GET /api/projects projeleri id, title, slug, visibility, category, coverUrl, tourCount, imageCount, videoCount ve tarihlerle listeler; GET /api/projects/{id} bunlara description, location, tags, urls (public ve gizli bağlantı), sahneleriyle birlikte tours ile galerideki images, videos ve işaretleriyle birlikte floorplans alanlarını ekler. Proje oluşturmak ve medya eklemek için stüdyoyu kullan.

İstatistikler

GET /api/stats/{contentId}?range=30 bir turun ya da projenin görüntülenmelerini döndürür. Ne alacağın pakete bağlıdır: Ücretsiz pakette tüm zamanların total değeri; Pro pakette sıfırlarla doldurulmuş günlük daily serisi (from, to, en çok 90 gün); Office ve Kurumsal paketlerde 365 güne kadar veri, ayrıca sources (sayfa, gömme, doğrudan), devices (telefon, masaüstü, VR gözlük), scenes ve gömen siteleri gösteren referrers. …/export.csv?range=30&table=daily günlük tabloyu, table=scenes sahne başına görüntülenmeleri, table=referrers ise gömen siteleri verir. Görüntülenmeler ziyaretçi adresi ve içerik başına, 30 dakikada bir kez sayılır; kişisel hiçbir veri saklanmaz.

Webhook’lar

Ayarlar → API bölümünde en çok beş webhook ekle. JSON gövdeli, imzalı bir POST göndeririz:

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

Olay	Ne zaman	Veri
scene.ready	Sahne görünür oldu (önizleme karoları)	pending: hâlâ süren aşamalar — refine (tam çözünürlüklü karolar) ve vr (gözlük dokuları); önizleme son haliyse []
scene.sharpened	Tam çözünürlüklü karolar yerinde	stage: "refine", ok (aşama atlandıysa ve sahne önizleme kalitesinde kaldıysa false), pending
scene.vr_ready	VR dokuları yerinde	stage: "vr", ok, pending
scene.failed	İşleme kalıcı olarak başarısız oldu	Nedeniyle birlikte error
ping	“Test gönder” düğmesi	boş

Başlıklar: Prewalk-Signature: ts=<unix seconds>;h1=<hex>; burada h1, webhook imza anahtarınla ts + ":" + body üzerinden hesaplanan HMAC-SHA256 değeridir (tam olarak aldığın baytlar üzerinden hesaplanır); ayrıca Prewalk-Event-Id ve Prewalk-Event-Type. İmza anahtarı yenilenirken, önceki anahtarın süresi dolana kadar başlık iki h1 değeri taşır (ts=…;h1=<new>;h1=<old>): herhangi biri doğrulanırsa gönderimi kabul et. İmzayı doğrula, birkaç dakikadan eski bir zaman damgasını reddet ve tekrarları eventId ile ayıkla: bir gönderim, uç noktan 2xx yanıtı verene kadar yeniden denenir (on deneme, önce 30 sn, sonra her seferinde iki katı, toplamda yaklaşık dört saat) ve yeniden denenen gövde bayt bayt aynıdır. Art arda 20 başarısız gönderimden sonra webhook kapatılır ve hesap sahibine bir e-posta gider. Uç noktalar, herkese açık bir adreste https kullanmalıdır; yönlendirmeler izlenmez. İmza anahtarı yenilenebilir; öncekisi 24 saat geçerli kalır.

Adım adım örnek

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

# 2. iki sahneyi sırayla yükle
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. kategori belirle ve yayımla
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. son 30 günün görüntülenmeleri
curl -s "https://prewalk.co/api/stats/$TOUR?range=30" -H "Authorization: Bearer $PW_KEY"

Gömme

Gömme için anahtar gerekmez: her turun bir https://prewalk.co/embed/{id} adresi vardır ve embed.js çerçeveyi boyutlandırıp turu senin sayfanda tam ekran açar. Gömülü içeriklerinin hangi web sitelerinde görünebileceğini Ayarlar → Marka bölümünde belirlersin. Ayrıntılar gömme rehberinde.

Hata kodları

Durum	Kod	Anlamı
400	invalid_request	Bir alan eksik ya da geçersiz; hangisi olduğunu field söyler
400	unsupported_format, unsupported_ratio, unreadable_image, rights_required, category_required, project_needs_content	Yükleme ya da yayımlama ön koşulları (projede herkese açık bir tur, bir görsel ya da bir video olmalıdır)
401	unauthorized, invalid_api_key	Hiç anahtar yok ya da anahtar hatalı biçimli veya iptal edilmiş
402	plan_required, quota_exceeded	Paket bu özelliği içermiyor ya da bir sınıra ulaşıldı (hangisi olduğunu feature ya da limit söyler)
403	api_key_forbidden, api_scope_missing	Uç nokta anahtarlara açık değil ya da anahtarda bu kapsam yok
404	not_found	Senin değil, silinmiş ya da böyle bir kimlik yok
409	revision_conflict, slug_taken, in_password_project	Eş zamanlı düzenleme (güncel tur yanıtta yer alır), adres kullanımda, proje şifresi kuralı
413	file_too_large	Boyut sınırının üstünde
429	rate_limited	Çok fazla istek; Retry-After saniye bekle
503	maintenance	Prewalk güncelleniyor; bir dakika sonra yeniden dene

Değişiklikler

• 10 Kasım 2026: yalnız görsellerden ya da videolardan oluşan bir proje de artık yayımlanabiliyor veya şifreyle korunabiliyor. Gösterecek hiçbir şeyi olmayan bir proje, herkese açık da olsa şifreli de olsa 400 project_needs_content döndürüyor; bu kod artık gönderilmeyen project_needs_public_tour ve project_needs_tour kodlarının yerini alıyor. GET /api/projects artık videoCount da döndürüyor.
• 22 Ekim 2026: scene.ready artık pending taşıyor; yeni olaylar scene.sharpened ve scene.vr_ready; yükleme sırası başlıkları x-pw-upload-batch ve x-pw-upload-index; anahtarla çağrılan GET /api/me yalnız anahtarın hesabını açıklıyor.

Soruların mı var ya da bir uç nokta mı eksik? hello@prewalk.co adresine yaz.