Oturumlar API'si

Oturum, CID222'nin sizin adınıza tuttuğu konuşma durumudur: mesaj geçmişi, kümülatif token kullanımı ve modele gönderilen, otomatik olarak özetlenmiş bir bağlam. Siz her seferinde tek bir mesaj gönderirsiniz, geçmişi CID222 sağlar.

Uç noktalar

POST /sessions ve POST /sessions/:id/messages birer yazma işlemidir ve auditor rolü için 403 ve ROLE_NOT_FOR_CHAT ile reddedilir. Okuma ve silme işlemleri çağıranın kendi kiracısıyla sınırlıdır.

Oturum oluşturma

POST /sessions

Model ve sağlayıcı, oluşturma anında değil, mesaj başına seçilir.

curl -sS -X POST "https://<appliance-fqdn>/sessions" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"session_name":"Support chat","user_id":"user-123"}'

{
  "id": "6f1c2e7a-9b3d-4f5a-8c21-0d9a1b2c3d4e",
  "tenant_id": "b2c3d4e5-6f70-4a81-9b2c-3d4e5f607182",
  "user_id": "user-123",
  "session_name": "Support chat",
  "context": [],
  "token_usage": { "total_tokens": 0, "total_cost": 0 },
  "last_used_at": "2026-09-10T10:30:00.000Z",
  "created_at": "2026-09-10T10:30:00.000Z"
}

updated_at alanı yoktur. Güncellik bilgisini last_used_at taşır.

Mesaj gönderme

POST /sessions/:id/messages text/event-stream döndürür.

curl -N -sS -X POST \
  "https://<appliance-fqdn>/sessions/6f1c2e7a-9b3d-4f5a-8c21-0d9a1b2c3d4e/messages" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"content":"I need help with my order 12345","model":"gpt-4o","provider":"openai"}'

Akış

Sözleşme POST /chat/completions ile aynıdır — arabelleğe alınmış, yanıtın tamamı tek bir filtered-response olayında ve ardından data: [DONE] — iki farkla.

user_message_processed burada iletilir. Oturum yolu bu kontrol olayını geçirir; böylece bir arayüz, model görmeden önce istemde neyin maskelendiğini gösterebilir:

data: {"type":"user_message_processed","content":"My name is [NAME] and my email is [EMAIL]","original_had_issues":true,"entities_count":2,"masked_count":2,"flagged_count":0,"action_taken":"masked","filter_duration_ms":142}

data: {"type":"token_usage","usage":{"prompt_tokens":320,"completion_tokens":12,"total_tokens":332}}

data: {"id":"filtered-response","content":"Hello. How can I help you today?","finish_reason":"stop","filtered":false,"entities_masked":0}

data: [DONE]

Ön filtre reddi farklı bir biçim taşır. Oturumun kendi girdi filtresi mesajı sohbet servisi çağrılmadan önce reddettiğinde olayda error alanı bulunmaz:

data: {"type":"content_rejected","reason":"Content policy violation: jailbreak","categories":["jailbreak"],"scores":{"jailbreak":0.96},"filter":"content-safety-v2 v2","filter_duration_ms":138}

data: [DONE]

Daha aşağıda, sohbet servisi içinde oluşan bir reddetme, Sohbet API'si sayfasında belgelenen {"error":…,"type":"content_rejected","entities":[…]} biçimini kullanır. İkisini de ele alın: error alanının varlığına değil, type === "content_rejected" koşuluna bakın.

Diğer her şey — user_locked, security_warning, token_usage, output_content_rejected, output_content_warning, [DONE] — /chat/completions üzerindeki gibi davranır. hallucination diye bir olay yoktur.

Tek bir oturumu alma

GET /sessions/:id, oturumu eksiksiz context alanıyla döndürür.

{
  "id": "6f1c2e7a-9b3d-4f5a-8c21-0d9a1b2c3d4e",
  "tenant_id": "b2c3d4e5-6f70-4a81-9b2c-3d4e5f607182",
  "user_id": "user-123",
  "session_name": "Support chat",
  "context": [
    { "role": "user", "content": "I need help with my order 12345", "model": "gpt-4o", "delta_tokens": 12 },
    { "role": "assistant", "content": "Let me look that up for you.", "model": "gpt-4o", "delta_tokens": 9 }
  ],
  "token_usage": { "total_tokens": 21, "total_cost": 0.00019 },
  "summarization_info": {
    "ai_context_tokens": 21,
    "summarization_threshold": 4000,
    "tokens_until_summarization": 3979,
    "summarization_enabled": true
  },
  "summarization_history": [],
  "has_hallucination_warning": false,
  "hallucination_warnings": [],
  "last_used_at": "2026-09-10T10:35:00.000Z",
  "created_at": "2026-09-10T10:30:00.000Z"
}

context içindeki her kayıt ayrıca timestamp, content_hash, had_detections, detection_summary, filter_duration_ms, llm_duration_ms, is_rejected, rejection_reason ve imageBase64 taşıyabilir.

Yanıt türü ayrıca context_window_usage alanını tanımlar, ancak oturum rotaları bu alanı doldurmaz. Varlığına güvenmeyin.

Oturumları listeleme

GET /sessions, kimliği doğrulanmış kiracıya ait her sohbet oturumunu last_used_at alanına göre azalan sırada döndürür.

Liste satırları geçmişi kasıtlı olarak dışarıda bırakır — bir oturum megabaytlarca base64 görüntü tutabilir. Her satır context alanını boş bir dizi olarak ve yanında bir message_count döndürür:

[
  {
    "id": "6f1c2e7a-9b3d-4f5a-8c21-0d9a1b2c3d4e",
    "tenant_id": "b2c3d4e5-6f70-4a81-9b2c-3d4e5f607182",
    "user_id": "user-123",
    "session_name": "Support chat",
    "context": [],
    "message_count": 2,
    "token_usage": { "total_tokens": 21, "total_cost": 0.00019 },
    "has_hallucination_warning": false,
    "last_used_at": "2026-09-10T10:35:00.000Z",
    "created_at": "2026-09-10T10:30:00.000Z"
  }
]

Yalnızca sohbet türündeki oturumlar listelenir. Görüntü taramaları ve oturumsuz API trafiği için örtük olarak oluşturulan oturumlar listede yer almaz; bunun yerine tespitler altında görünür.

Oturumu yeniden adlandırma

PATCH /sessions/:id, en fazla 100 karakterlik bir session_name alır ve güncellenmiş oturumu döndürür.

Oturumu silme

DELETE /sessions/:id oturumu kaldırır. İlişkili tespit kayıtları basamaklı silme ile birlikte kaldırılır.

{ "message": "Session deleted successfully" }

Bağlam yönetimi

• Tam geçmiş context alanında saklanır ve GET /sessions/:id tarafından döndürülür.
• Model bağlamı ayrıdır. CID222 ikinci, özetlenmiş bir bağlam tutar ve sağlayıcıya onu gönderir.
• Özetleme eşiğe bağlıdır, modele değil. Özetlenmiş bağlam context_summarization_threshold_tokens değerine — varsayılan 4000 — ulaştığında CID222 eski mesajları özetler ve olayı summarization_history içine kaydeder. Tetikleyici, modelin bağlam penceresi değil, yapılandırılmış bu token sayısıdır. Kapatmak için context_summarization_enabled değerini false yapın.
• Token kullanımı oturum başına birikir: token_usage.total_tokens ve token_usage.total_cost.
• Halüsinasyon uyarıları oturuma yazılır. Arka plandaki bağlam doğrulama kontrolü has_hallucination_warning alanını yazar ve hallucination_warnings dizisine ekleme yapar. Akışta hiçbir zaman görünmez.

Hatalar

İlgili

• Sohbet API'si — durumsuz eşdeğeri ve SSE olay listesinin tamamı.
• Kimlik doğrulama — bu rotaların ihtiyaç duyduğu JWT'yi alma.
• API genel bakış — her yüzeyde temel yollar ve hata biçimleri.