Prompt Universe API

Genel bakış

API küçük ve workspace kapsamlıdır. Her yanıt bir { data, meta } zarfına sarılır; hatalar üst düzey bir error nesnesi döner (bkz. Hatalar). Build'ler bir worker üzerinde asenkron çalışır; bu yüzden oluşturma hemen döner ve ilerlemeyi siz izlersiniz.

Base URL

https://api.universe.searchestra.com

Kurallar

• Tüm istek ve yanıt gövdeleri application/json'dır.
• Başarılı yanıtlar üst düzey bir data alanı ve opsiyonel meta taşır. Hatalar üst düzey bir error alanı taşır.
• Her /v1/* ucu X-API-Key başlığını gerektirir. /healthz ve /metrics gerektirmez.
• Kimlikler UUID'dir; version'lar semantiktir (MAJOR.MINOR.PATCH, örneğin 1.0.0).
• Zaman damgaları UTC, ISO 8601'dir (örneğin 2026-08-19T13:47:09Z).

Yaşam döngüsü

Bir universe sabit bir yaşam döngüsünden geçer. Her build aday query'ler üretir, tam intent kapsamıyla temsil edici bir alt küme seçer ve siz memnun olunca değişmez bir version'a kilitlenir.

universe yarat  ──▶  build (async pipeline)  ──▶  status: ready
     │                                                  │
     │                                          version kilitle ──▶  1.0.0 (değişmez)
     │                                                  │
  refresh ◀───────────  yeni build  ◀── scheduled_review │ structural_market_change
                                                         ▼
                                      manifest + query'leri oku (intent'e göre)

Kilitli bir version asla değişmez. Bir universe'i evrimletmek için bir refresh tetiklersiniz; bu yeni bir version kilitleyen yeni bir build başlatır ve eskisini tarihsel karşılaştırma için korur.

Hızlı başlangıç

Bir universe yaratın, build'i bekleyin, kilitleyin, ardından query'leri okuyun. un_your_key'i workspace'inize verilen anahtarla değiştirin (bkz. Kimlik doğrulama).

1 · Build başlat

curl -X POST https://api.universe.searchestra.com/v1/universes \
  -H "X-API-Key: un_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "proje yönetim yazılımı",
    "market": "TR",
    "language": "tr",
    "requested_query_count": 120
  }'

{
  "data": {
    "id": "b3f1c2a4-...",
    "universe_id": "9a71e0d2-...",
    "status": "queued",
    "requested_query_count": 120,
    "created_at": "2026-08-19T13:47:09Z"
  }
}

2 · Build'i izle

curl https://api.universe.searchestra.com/v1/universes/9a71e0d2-.../builds/b3f1c2a4-.../status \
  -H "X-API-Key: un_your_key"

{
  "data": {
    "status": "running",
    "progress": { "stage": 4, "total_stages": 7, "percentage": 57 },
    "queries_target": 120,
    "queries_selected": 0,
    "candidates_generated": 210
  }
}

3 · Version'ı kilitle

curl -X POST https://api.universe.searchestra.com/v1/universes/9a71e0d2-.../builds/b3f1c2a4-.../lock \
  -H "X-API-Key: un_your_key"

{
  "data": {
    "version": "1.0.0",
    "build_id": "b3f1c2a4-...",
    "universe_id": "9a71e0d2-...",
    "query_count": 120,
    "taxonomy_version": "1.0.0",
    "baseline": { "reset_required": false, "compatible_with_previous": null },
    "locked_at": "2026-08-19T13:59:41Z"
  }
}

4 · Query'leri oku

curl "https://api.universe.searchestra.com/v1/universes/9a71e0d2-.../versions/1.0.0/queries?intent=recommendation" \
  -H "X-API-Key: un_your_key"

Kimlik doğrulama

Her /v1/* isteği X-API-Key başlığında bir API anahtarı taşımalıdır. Anahtarlar un_ ön ekiyle başlar ve bir kullanıcıyı değil, bir workspace'i tanımlar.

X-API-Key: un_your_key

Anahtarlar workspace başına workspaceinit komutuyla üretilir. Ham değer yalnızca üretim anında bir kez gösterilir ve geri alınamaz; sunucu yalnızca bir hash saklar. Bir workspace birden çok anahtar tutabilir; birini iptal etmek diğerlerini etkilemez.

Universe yarat

Yeni bir universe yaratır ve ilk build'ini asenkron başlatır. Build ile birlikte 201 döner; pipeline bir worker'da devam eder. İlerleme için build durumunu izleyin.

İstek gövdesi

Build durumu

Build'in ilerlemesini döner. status terminal bir duruma (örneğin ready ya da failed) ulaşana kadar bunu izleyin.

{
  "data": {
    "status": "ready",
    "progress": { "stage": 7, "total_stages": 7, "percentage": 100 },
    "queries_target": 120,
    "queries_selected": 120,
    "candidates_generated": 240
  }
}

Universe'i ve build'lerini birlikte incelemek için GET /v1/universes/{id} çağırın. Build başına sağlık özeti .../builds/{build_id}/health'te bulunur.

Version kilitle

Hazır bir build'i değişmez, semantik versiyonlu bir universe'e dondurur. Kilitlendikten sonra o version'ın manifest ve query'leri asla değişemez.

Bir universe'in tam olarak tek aktif build'i varsa, alias POST /v1/universes/{id}/lock onu build id olmadan kilitler. Hazır olmayan bir build'i ya da alias ile birden çok aktif build'i olan bir universe'i kilitlemek 409 conflict döner.

Manifest getir

Version'ın Universe Manifest'ini döner: bu universe'in nasıl örneklendiğinin değişmez tanımı — taxonomy, intent dağılımı, kapsam ve provenance. Bir ölçüm koşusunun sabitlendiği referans budur.

Alias GET /v1/universes/{id}/manifest en son kilitli version'ın manifest'ini döner. Intent kapsamı ayrıca GET /v1/universes/{id}/coverage'ta özetlenir.

Query'leri listele

Kilitli bir version'ın query'lerini döner. Her query eksiksiz, stabil intent metadata'sı taşır; böylece ölçümü intent'e göre segmentleyebilirsiniz.

Query parametreleri

Alias GET /v1/universes/{id}/queries en son kilitli version'ın query'lerini listeler.

Universe'i yenile

Universe'i evrimletmek için yeni bir build tetikler. Eski version kilitli ve karşılaştırılabilir kalır; yeni build yeni bir version kilitler.

Evidence dataset'leri

Opsiyonel. Gözlenmiş talebin (gerçek dünyada görülen sorular) bir dataset'ini yaratın, ardından içine item'lar ingest edin. Bir build intent_policy: observed_weighted kullandığında, bu dataset'ler örneklemeyi topraklar; böylece oranlar pazarın gerçekte ne sorduğunu yansıtır.

curl -X POST https://api.universe.searchestra.com/v1/evidence/datasets \
  -H "X-API-Key: un_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "TR PM arama logları Q3", "source_summary": "anonimleştirilmiş site araması" }'

POST /v1/evidence/datasets/{id}/items ile item ingest edin, ardından dataset id'sini bir universe'in control_plane.evidence_dataset_ids'inde referans verin.

Intent'ler

Her query tam olarak bir intent'e sınıflanır. Dördünün tümü boyunca kapsam şansa bırakılmaz, bilerek planlanır.

Versiyonlama & baseline

Version'lar değişmez ve semantiktir. Bir ölçüm koşusu belirli bir version'a referans verir; bu tarihsel karşılaştırılabilirliği garanti eder: geçen çeyreğin sayılarının ardındaki tam soru seti hâlâ değişmeden durur.

• Değişmez: kilitlendikten sonra bir version'ın manifest ve query'leri asla değişmez.
• Baseline bildirimi: bir kilit, compatible_with_previous olup olmadığını raporlar. reset_required true olduğunda, ölçüm yeni bir baseline başlatmalı ve sınırın iki yanını birleştirmemelidir.
• Refresh: bir universe'i evrimletmek yeni bir version demektir, eskisinin düzenlenmesi değil.

Hatalar

Hatalar bir code, bir message ve opsiyonel details içeren bir error nesnesi döner.

{ "error": { "code": "unauthorized", "message": "X-API-Key required." } }

Bütçeler & limitler

Bir build LLM çağırdığından, her build açık guard'lar altında çalışır; böylece bir universe sınırsızca maliyet ya da süre tüketemez.

Bütçeler planınızla ölçeklenir. Kesin varsayılanlar (query sayısı, maliyet, süre) deployment başına ayarlanır.