For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /tr/docs/web/api.md (or send Accept: text/markdown).

Herkese açık API, anahtarlar ve webhook'lar

Müşterilerinizin üzerine inşa ettiği sürümlenmiş REST yüzeyi.

Bu kılavuz hakkında sor

Başlamadan önce

İndirdiğiniz supastack projenizi Visual Studio Code'de Dosya → Klasörü Aç'ı kullanarak açın ve ardından Terminal → Yeni Terminal'i seçin. Depo kökü package.json'u, uygulamaları ve paketleri içeren klasördür. Aşağıdaki komutu orada çalıştırın ve terminalini açık bırakın. Bir komut tanınmazsa devam etmeden önce araç kurulum kılavuzunu tamamlayın.

Önce platform eğitimini okuyun. Sunucu, tarayıcı veya telefon isteklerini yanıtlayan uygulama işlemidir. Web, apps/web/.env.local'yi okur, Expo, apps/mobile/.env.local'yi okur ve veritabanı geçiş komutları root .env'yi okur. Veritabanı olmayan/gösterge paneli gösterimi, Postgres'nin taşınmasını gerektiren gerçek/auth hesaplarından ayrıdır. Yalnızca telefona veya masaüstüne yönelik bir ödeme, ayrı olarak çalışan bir Web arka ucuna ihtiyaç duyar.

corepack pnpm --filter @supastack/web dev

Kurulum ve yapılandırma

packages/api sürümlenmiş sözleşmeyi tanımlar: her istek ve yanıt için zod şemaları, hata zarfı ve /api/v1/openapi'de sunulan ve /api/docs'ta işlenen OpenAPI belgesi. Çalışma alanı API anahtarları Ayarlar → Geliştiriciler altında oluşturulur; düz metin bir kez gösterilir, sonra yalnızca karma anahtar kalır.

Anahtarlar öneklidir (sk_<env>_…), kapsamlıdır (varsayılan okuma) ve her istekte bir çalışma alanına çözülür. Giden webhook abonelikleri aynı Geliştiriciler yüzeyinden yönetilir.

GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…

Uygulama iş akışı

Bearer anahtarıyla kimlik doğrulayın; sunucu çalışma alanını anahtardan çözer, asla istemci tarafından sağlanan kimlikten değil. Yanıt şekillerini sürümlenmiş tutun — v1 içinde eklemeli değişiklikler, kırıcı değişiklikler yeni sürüm arkasında.

Giden webhook'lar için bir uç nokta URL'sini olay kataloğuna abone edin; teslimatlar imzalanır ve kaydedilir, böylece tüketiciler doğrulayabilir ve yeniden oynatabilir. Katalog için webhook-events.ts, denemeler için webhook-delivery.ts kullanın.

Doğrulama ve sorun giderme

İptal edilmiş anahtarın 401 döndürdüğünü, yetersiz kapsamlı anahtarın reddedildiğini ve OpenAPI belgesinin ayrıştığını doğrulayın. Webhook'lar için imza doğrulamasını, hata sonrası yeniden teslimi ve olay yüklerinin asla sağlayıcı sırları taşımadığını test edin.