VoxSim API v1

1. Genel bakış

VoxSim API v1, REST + JSON arayüzüdür. Sanctum bearer-token kimlik doğrulaması kullanır ve workspace'inize bağlı tokenlerle scope'lanır. Her cevap zarflanır (data + meta veya error).

• Temel URL: https://voxsim.talivio.com/api/v1
• Format: JSON, UTF-8
• Rate limit: Şu an enforcement yok; kötüye kullanım gözlenirse plan-bazlı hız limiti uygulanacak (Atölye 60/saat, Saha 600/saat, Karargah 6.000/saat planlanıyor)
• Sürüm: URL prefix (/v1)

Cevap zarfı

Tüm başarılı cevaplar şu yapıdadır:

{
  "data": { ... },
  "meta": {
    "api_version": "v1",
    "generated_at": "2026-04-29T12:34:56+00:00",
    "pagination": {
      "total": 124,
      "per_page": 20,
      "current_page": 1,
      "last_page": 7
    }
  }
}

2. Kimlik doğrulama

Bearer token kimlik doğrulaması. Her workspace için ayrı token oluşturursunuz; token'a o workspace'e bağlı izin (workspace:{id}) iliştirilir.

1. Şuraya gidin: Workspace → API ayarları
2. Token oluşturun (sadece workspace sahibi yapabilir).
3. Tokenı kopyalayın — bir daha gösterilmez. Authorization header'ında kullanın.

curl https://voxsim.talivio.com/api/v1/me \
  -H "Authorization: Bearer 1|abc123def456..." \
  -H "Accept: application/json"

Tokenları asla kod tabanına commit etmeyin, public client'larda göstermeyiniz, .env veya secret manager kullanın.

3. GET /me

Kimliği doğrulanan kullanıcı, aktif workspace ve token meta-bilgisi.

Örnek cevap

{
  "data": {
    "user": {
      "id": 1,
      "name": "Eren Erdem",
      "email": "[email protected]",
      "role_in_workspace": "owner"
    },
    "workspace": {
      "id": 1,
      "name": "Talivio Lab",
      "slug": "talivio-lab",
      "plan": "karargah",
      "modules_unlocked": ["a","b","d","f","g","h","i","j"],
      "seats_used": 1,
      "seats_max": 10,
      "status": "active"
    },
    "token": {
      "name": "production-server",
      "abilities": ["workspace:1"],
      "last_used_at": "2026-04-29T12:30:00+00:00"
    }
  },
  "meta": { ... }
}

4. GET /simulations

Workspace'inizdeki simülasyonların paginated listesi. En yeni en üstte.

Sorgu parametreleri

• module — a, b, d, f, g, h, i, j
• status — queued, running, completed, failed, cancelled
• per_page — 1-100, default 20

curl "https://voxsim.talivio.com/api/v1/simulations?module=a&status=completed&per_page=10" \
  -H "Authorization: Bearer 1|abc..."

5. GET /simulations/{public_id}

Tek bir simülasyonun tüm detayı (segments, sample quotes, cost, hata mesajı dahil).

{
  "data": {
    "public_id": "01KQB4535MXAN9C951181RPWX3",
    "title": "Asgari ücret söylemi",
    "module": "a",
    "status": "completed",
    "persona": { "id": 1, "name": "Örnek Aday A", "short_code": "ornek-aday-a" },
    "policy_text": "...",
    "result_segments": {
      "sosyal_demokrat": {"anger":35,"fear":70,"apathy":5,"hope":5,"support":10}
    },
    "result_summary": { ... },
    "tokens_in": 1728,
    "tokens_out": 8322,
    "cost_eur": 0.0438,
    "accuracy_score": null,
    "completed_at": "2026-04-28T16:48:35+00:00"
  }
}

6. POST /simulations

Yeni Modül A (Söylem Testi) simülasyonu oluşturur ve kuyruğa koyar. Çalışan worker bunu işler. Asenkron — istek anında 201 döner; sonuç ayrı GET ile alınır.

İstek gövdesi

{
  "persona_id": 1,
  "title": "Asgari ücret söylemi",
  "policy_text": "Asgari ücret 30.000 TL'ye yükselmeli...",
  "mock": false
}

mock=true geçerseniz LLM çağrısı yapılmaz, sentetik mock data döner (test/CI için).

Örnek

curl -X POST https://voxsim.talivio.com/api/v1/simulations \
  -H "Authorization: Bearer 1|abc..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "persona_id": 1,
    "title": "Test simulation",
    "policy_text": "Asgari ücreti enflasyon karşısında eritmeyeceğiz...",
    "mock": false
  }'

İstek 201 döner, status=queued. Worker (Horizon) işlemeye başladığında running olur, ~60-120 saniye sonra completed.

7. GET /personas

Workspace'inizdeki tüm aktif persona'lar (draft, awaiting_approval, approved). Simülasyon oluştururken persona_id parametresi için kullanılır.

{
  "data": [
    {
      "id": 1,
      "name": "Örnek Aday A",
      "short_code": "ornek-aday-a",
      "is_known": true,
      "status": "approved",
      "axes": {"economic": 2, "cultural": 4, "religious": 2, "nationalist": 3}
    }
  ]
}

7.1 Ek endpoint'ler

GET /api/v1/usage

Cari ay kullanım özeti: modüle göre simülasyon sayıları, plan limitleri, token ve tahmini maliyet.

curl https://voxsim.talivio.com/api/v1/usage \
  -H "Authorization: Bearer $VOXSIM_TOKEN"

POST /api/v1/personas

Yeni persona programatik olarak oluşturur. Zorunlu: name + axes (her eksen 1-5). Otomatik onaylanır.

curl -X POST https://voxsim.talivio.com/api/v1/personas \
  -H "Authorization: Bearer $VOXSIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Örnek Aday A",
    "axes": {"economic": 2, "cultural": 4, "religious": 2, "nationalist": 3},
    "tagline_tr": "Sosyal demokrat aday"
  }'

POST /api/v1/simulations/{id}/counter-narrative

Modül F (Saha+). En yüksek öfke segmentine alternatif çerçeveleme simülasyonu başlatır.

POST /api/v1/simulations/{id}/optimizer

Modül I (Saha+). 6 sıralı politika varyantı üretir. Manipülatif varyantlar etik filtresiyle reddedilir.

POST /api/v1/simulations/{id}/crisis-break

Modül B (Karargah+). Savunma odaklı kırılganlık analizi. PDF çıktısı 30 gün sonra otomatik sona erer.

GET /api/v1/simulations/{id}/report

Filigranlı PDF ikili verisi döner. X-Watermark-Token cevap başlığı doğrulama token id'sini içerir.

curl https://voxsim.talivio.com/api/v1/simulations/{public_id}/report \
  -H "Authorization: Bearer $VOXSIM_TOKEN" \
  -o report.pdf

DELETE /api/v1/simulations/{id}

Geçici silme (durum → iptal edildi). Denetim kaydı EU AI Act gereği 6 ay korunur. Simülasyon çalışıyor veya kuyruktaysa reddedilir.

8. Hata yönetimi

Hata cevapları HTTP status + JSON gövde ile döner:

{
  "error": {
    "code": "persona_not_in_workspace",
    "message": "Persona not accessible in this workspace",
    "details": []
  }
}

Hata kodları