Belgeler

API referansı

Bu, kapalı beta boyunca Gurulu Gerçek Katmanı'nın herkese açık REST yüzeyidir. Yönetici, iç operasyon ve platform gözlemlenebilirlik uçları burada listelenmez — onlar operatör kimlik bilgileriyle sınırlıdır ve müşteri sözleşmesinin parçası değildir.

İki temel adres:

  • Veri düzlemi — https://ingest.gurulu.io. Olay kabul eden her şey.
  • Kontrol düzlemi — https://api.gurulu.io. Geri kalan her şey.

Kimlik doğrulama

İki kimlik bilgisi tipi:

  • Bearer JWT. Giriş yapmış bir kullanıcıya sihirli bağlantı (birincil) ya da OAuth (Google veya GitHub, PKCE S256) ile verilir. İnsanın yaptığı kontrol düzlemi çağrılarında kullanılır.
  • API anahtarı. İki çeşit. pk_live_* herkese açık anahtardır — tarayıcı koduna konması güvenlidir, tarayıcı SDK'sı kullanır. sk_live_* gizli anahtardır — tarayıcıya asla gitmez, sunucu SDK'sı ve doğrudan REST çağıranlar kullanır.

Tüm yanıtlar UTF-8 JSON'dur. Hatalar RFC 7807 application/problem+json biçimini izler.

Kimlik doğrulama uçları

POST   /v1/auth/magic-link             Sihirli bağlantı e-postası iste
POST   /v1/auth/magic-link/verify      Sihirli bağlantı jetonunu oturuma çevir
GET    /v1/auth/oauth/:provider        OAuth başlat (Google veya GitHub)
POST   /v1/auth/session/refresh        Erişim jetonunu tazele
POST   /v1/auth/session/revoke         Oturumu iptal et
POST   /v1/auth/api-keys               Yeni API anahtarı üret

Alım — olay gönderme

Herkese açık veri düzlemi. Doğrulama kapısı burada koşar.

POST   /v1/track                       Tek bir olay gönder
POST   /v1/batch                       Tek çağrıda N olaya kadar gönder
POST   /v1/identify                    Bir anonymous_id'yi person_id'ye bağla
POST   /v1/alias                       İki kimliği birleştir
POST   /v1/webhook/:provider           Bir tedarikçi webhook'u al

Gövdedeki her olay doğrulama kapısını geçmelidir. Olay başına olası sonuçlar:

  • accept — kayıtlı, iyi biçimli, bilinen. Geçer.
  • warn — ölümcül olmayan bir sorunla kabul edildi (beklenmeyen özellik tipi, kullanımdan kaldırılmış anahtar).
  • quarantine — inceleme için tutuldu. Alt akış hedeflerine ulaşmaz.
  • reject — reddedildi. Yanıtta gerekçesiyle döner.

Kayıt — sözleşme

Kayıt, olay adları ve şekilleri için gerçeğin kaynağıdır. Olay anahtarları ^[a-z0-9_]+$ desenine uymalıdır.

GET    /v1/registry/events             Olay sözleşmelerini listele
POST   /v1/registry/events             Yeni olay sözleşmesi oluştur
GET    /v1/registry/events/:key        Tek bir sözleşmeyi oku
POST   /v1/registry/validate           Bir yükü kayda göre doğrula
GET    /v1/registry/code-gen           Bir ortam için tipli kod üretimi al
GET    /v1/registry/packs              Sektör başlangıç paketlerini listele

Kod üretimi TypeScript, Python ve Swift için tipli bağlamalar döner. CLI (gurulu pull) bu uçları sarmalar ve sonucu deponuza yazar.

Kimlik — omurga

Yedi adımlı çözüm, üç düzeyli güven, yalnızca ekleme yapılan birleştirme defteri. Her birleştirme geri alınabilir.

POST   /v1/identity/resolve            Bir tanımlayıcı kümesini person_id'ye çöz
GET    /v1/identity/person/:id         Bir kişi kaydını oku
GET    /v1/identity/person/:id/timeline   Bir kişinin olay zaman çizelgesini al
POST   /v1/identity/merge              İki kaydı açıkça birleştir
GET    /v1/identity/merge-ledger       Yalnızca eklenen birleştirme günlüğünü oku

Sağlık — kalite sinyali

Olay sağlığı: anomali tespiti, yinelenen ayıklama, kapsam, CAPI uyumsuzluğu.

GET    /v1/health/events               Çalışma alanı genelinde sağlık özeti
GET    /v1/health/events/:key          Olay başına sağlık
GET    /v1/health/anomalies            Tespit edilen anomaliler (hacim, şema, gecikme)
GET    /v1/health/coverage             Yüzey başına kapsam puanı
POST   /v1/health/dedup-check          İki kayıt yinelenmiş görünüyor mu sor

Atıf — kredi ve köken

Müşterinin tanımladığı politika, çok modelli (ilk, son, doğrusal, zamanla azalan, konum, veri odaklı) ve sonuç başına tam köken izi.

POST   /v1/attribution/policy                       Atıf politikasını tanımla / güncelle
POST   /v1/attribution/compute                      Bir tarih aralığı için atfı yeniden hesapla
GET    /v1/attribution/touchpoints/:personId        Bir kişi için dikkate alınan temas noktaları
GET    /v1/attribution/explain/:outcomeId           Belirli bir sonuç için açıklama izi

explain ucu şunları döner: hangi temas noktaları dikkate alındı, hangileri dışlandı, hangi model uygulandı ve alternatif modeller neye kredi verirdi.

İzin — GDPR, KVKK, CCPA

GCM v2 kategorileri. DSR dışa aktarma ve unutulma, 60 saniyelik SLA kuyruğunda.

POST   /v1/consent                     Bir kişi için izin durumunu kaydet
GET    /v1/consent/:personId           Güncel izni oku
POST   /v1/consent/dsr/export          Veri dışa aktarma talebini kuyruğa al
POST   /v1/consent/dsr/forget          Unutulma talebini kuyruğa al

SDK'lar

Doğrudan REST kullanmak sorun değil. Çoğu ekip SDK'ları kullanıyor:

  • @gurulu/web — bağımlılıksız tarayıcı paketi (8,1 KB gzip). Beş otomatik yakalama sinyali, identify, track, izin, kayıt onayı.
  • @gurulu/node — Node 20+, Bun ve edge için sunucu SDK'sı. 23 tedarikçi için webhook doğrulayıcı. Hono, Express, Fastify için ara katman.
  • @gurulu/cli — gurulu init / pull / push / validate / doctor. Kaydı Git akışına bağlar.
  • @gurulu/mcp-server — Cursor, Claude Code, Lovable için MCP. Araçlar: list_events, add_event, validate_event. AI editörün olay adı tahmin etmeyi bırakır.

Hatalar

Tüm hatalar application/problem+json biçimindedir ve şunları taşır:

  • type — hata sınıfı için değişmeyen bir URL tanımlayıcısı.
  • title — kısa insan açıklaması.
  • status — HTTP durum kodu.
  • detail — bu istekte tam olarak ne ters gitti.
  • instance — hata bildirirken aktarabileceğin opak istek tanımlayıcısı.

Doğrulama kapısı reddi type: "https://gurulu.io/errors/contract-violation" biçimindedir. Yanıt gövdesi hangi alanların neden düştüğünü listeler.

Durum

Uç yüzeyinin tamamı bugün yaklaşık 270 rota; bu sayfa müşteriye dönük herkese açık alt kümeyi listeler. Operatör ve platform uçları müşteri sözleşmesinin parçası değildir ve haber verilmeden değişebilir. Yukarıdaki liste kapalı beta için değişmezdir.

Bu uçların arkasındaki kavramsal model için Nasıl çalışır sayfasına bak.

Belgelere dön