API docs by Redocly

KeysAi API (1.0.0)

Download OpenAPI specification:

KeysAi Support: support@keysai.com License: Proprietary

KeysAi servis talebi (case) triage, sınıflandırma ve öğrenme API'si.

Özellikler

  • AI destekli case triage ve önceliklendirme
  • Otomatik müşteri yanıt taslağı oluşturma
  • RAG (Retrieval Augmented Generation) ile geçmiş caselerden öğrenme
  • Multi-tenant destek
  • Dynamics 365 entegrasyonu

Authentication

Tüm endpoint'ler JWT Bearer token ile korunur.

Authorization: Bearer <your-jwt-token>

Cases

Case ingestion ve triage endpoint'leri

Yeni talep / case ingest

Mail veya web formdan gelen talebi KeysAi'ye gönderir.

İşlem Adımları:

  1. Request validasyonu
  2. AI destekli triage (RAG + OpenAI)
  3. Case oluşturma (Dynamics 365)
  4. Vector store'a kayıt (öğrenme için)
  5. Müşteri yanıt taslağı oluşturma

Dosya Gönderme:

  • JSON içinde URL ile (attachments array)
  • multipart/form-data ile binary dosya
Authorizations:
bearerAuth
Request Body schema:
required
message_id
required
string

Dış sistemdeki mail veya ticket id (unique)

tenant_id
required
string

Organizasyon / müşteri tenant id

channel
required
string
Enum: "Email" "Web" "Phone" "Chat"

Talebin geldiği kanal

subject
required
string

Mail subject veya kısa başlık

body
required
string

Talebin detay açıklaması (plain text veya HTML)

language_hint
string
Enum: "tr" "en"

Opsiyonel dil ipucu (ör. "tr", "en"). Boş bırakılırsa sistem tahmin eder.

object

İletişime geçen kişi bilgisi

object

Opsiyonel müşteri bilgisi. Dynamics'te lookup için ipucu olarak kullanılabilir.

object

Ön-doldurulmuş case alanları (opsiyonel). Eğer buradan gönderilirse, AI bu alanları değiştirmez, sadece doğrular.

Array of objects

Dosyalar URL ile gönderilecekse kullanılır. Sistem gerekirse buradan indirip OpenAI'ye yükler.

object

Yanıt içeriğini kontrol etmek için opsiyonel parametreler. Bu alanlar agentic response bölümlerini açıp kapatabilir (performans optimizasyonu için).

Responses

Request samples

Content type
Example
{
  • "message_id": "<unique-id@example.com>",
  • "tenant_id": "parge-soft",
  • "channel": "Email",
  • "subject": "NAV e-Fatura hatası",
  • "body": "GİB'e gönderirken UBL validation hatası alıyoruz",
  • "contact": {
    }
}

Response samples

Content type
application/json
{
  • "case_id": "CAS-125731",
  • "tenant_id": "parge-soft",
  • "vector_record_id": "vec_8df8b6b4-12ab-34cd-56ef-1234567890ab",
  • "keysai_result": {
    }
}

Case kapanış feedback

Case Dynamics'te kapandığında final alanlar ve gerçek çözümü KeysAi'ye gönderir.

Amaç:

  • Vector store'daki CASE_SNAPSHOT kaydını güncelle
  • AI tahminlerinin doğruluğunu ölç
  • Gelecek triagelar için öğrenme verisi oluştur
Authorizations:
bearerAuth
path Parameters
caseId
required
string
Example: CAS-125731

Dynamics case id

Request Body schema: application/json
required
tenant_id
required
string
vector_record_id
required
string

İlk triage sırasında oluşturulan vector store id

required
object

Dynamics'teki final case alanları

resolution_text
string

Gerçek çözüm açıklaması

final_customer_reply
string

Müşteriye gerçekten gönderilen son mail

object or null

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "parge-soft",
  • "vector_record_id": "vec_8df8b6b4-12ab-34cd-56ef-1234567890ab",
  • "final_case_fields": {
    },
  • "resolution_text": "GİB UBL schema 2.1'e güncellendi",
  • "final_customer_reply": "Sorun çözüldü",
  • "metrics": {
    }
}

Response samples

Content type
application/json
{
  • "case_id": "CAS-125731",
  • "vector_record_id": "vec_8df8b6b4-12ab-34cd-56ef-1234567890ab",
  • "status": "updated",
  • "message": "CASE_SNAPSHOT updated with final resolution. System learned from this case.",
  • "accuracy_metrics": {
    }
}

Files

Dosya yükleme endpoint'leri

Dosya yükle (OpenAI'ye forward edilecek)

Dosya KeysAi'ye yüklenir, OpenAI file servisine forward edilir ve openai_file_id döner.

Desteklenen Formatlar:

  • Dökümanlar: .pdf, .docx, .txt, .md
  • Resimler: .jpg, .png, .gif
  • Loglar: .log, .txt
  • Diğer: .xml, .json, .csv
Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
tenant_id
required
string
file
required
string <binary>

Upload edilecek dosya

Responses

Response samples

Content type
application/json
{
  • "file_id": "local-file-id-123",
  • "openai_file_id": "file-abc123xyz",
  • "file_name": "error-log.txt",
  • "content_type": "text/plain",
  • "size": 10240,
  • "tenant_id": "parge-soft",
  • "created_at": "2025-12-04T10:30:00Z"
}

Options

Option set ve configuration endpoint'leri

Option set değerlerini getir

Priority, case_type, origin gibi çekirdek setler veya product-family'ye göre subject listesi döner.

Kullanılabilir Setler:

Temel Setler:

  • priority - Case öncelik seviyeleri (HIGH, NORMAL, LOW)
  • status - Ana durum seviyeleri (ACTIVE, RESOLVED, CANCELLED)
  • status_reason - Detaylı durum açıklamaları (NEW, ON_PROCESS, PROBLEM_SOLVED, vb.)
  • case_type - Case türleri (QUESTION, REQUEST, ERROR, PROJECT_STEP)
  • origin - Talep kanalı (EMAIL, PHONE, WEB, TEAMS, API)

Organizasyon & Müşteri:

  • birim - Organizasyonel birim (YAZILIM, DANISMANLIK, YAZILIM_DANISMANLIK)
  • firma_durumu - Müşteri durumu (MUSTERI, PROSPECT, IS_ORTAGI, ESKI_MUSTERI)
  • faturalama_bilgisi - Faturalama tipi (FIX_COST, UNBILLABLE, TIME_AND_MATERIAL, PROJECT)

Ürün Bazlı (product_family parametresi gerekli):

  • subject - Ürün/modül bazlı konu listesi (örn: NAV için NAV_EFATURA, NAV_SATIS, vb.)
  • project_step - Proje adımları (product_family'ye göre farklılaşır)

Kullanım Örnekleri:

GET /options/priority
GET /options/case_type
GET /options/subject?product_family=D365_BUSINESSCENTRAL_NAV
GET /options/status?language=en
Authorizations:
bearerAuth
path Parameters
setName
required
string
Enum: "priority" "status" "status_reason" "case_type" "origin" "birim" "firma_durumu" "faturalama_bilgisi" "subject" "project_step"
Example: priority

Option set adı

query Parameters
product_family
string
Enum: "D365_BUSINESSCENTRAL_NAV" "D365_Finance_Operations_AX" "D365_CRM_CE" "PowerPlatform" "PowerBI" "Azure" "Other"
Example: product_family=D365_BUSINESSCENTRAL_NAV

Subject veya project_step setleri için zorunlu parametre. Product family'ye göre ilgili subject veya proje adımlarını filtreler.

language
string
Default: "tr"
Enum: "tr" "en"
Example: language=tr

Dil seçeneği (tr=Türkçe, en=English)

Responses

Response samples

Content type
application/json
Example

Case öncelik seviyeleri. SLA süreleri ile ilişkilidir.

{
  • "set_name": "priority",
  • "product_family": null,
  • "language": "tr",
  • "values": [
    ]
}

Health

Sistem sağlık kontrolü

Sağlık kontrolü

Basit health check endpoint'i. Authentication gerektirmez.

Kontrol Edilen Servisler:

  • API sunucusu
  • OpenAI bağlantısı
  • Dynamics 365 bağlantısı
  • Vector store

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "uptime_seconds": 123456,
  • "version": "1.0.0",
  • "timestamp": "2025-12-04T10:30:00Z",
  • "dependencies": {
    }
}