> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flexy Chat (AI Streaming)

> Yapay zeka ile gerçek zamanlı (streaming) sohbet için kullanılan endpoint. Server-Sent Events (SSE) formatında yanıt döner.

<Warning>
  Bu endpoint özel bir **rate limit** (flexy-chat throttle) ile korunmaktadır. Limit aşıldığında `429 Too Many Requests` yanıtı döner.
</Warning>

## Endpoint özeti

| Metot  | Endpoint                    | Açıklama                         |
| ------ | --------------------------- | -------------------------------- |
| `POST` | `/api/v1/flexy-chat/stream` | AI ile streaming sohbet başlatır |

<Tip>
  Tüm parametreler ve örnek istek/yanıtlar için **[API Referansı](/api-reference)** sekmesine bakın.
</Tip>

## Flexy Chat kavramı

Flexy Chat, yapay zekaya bir `prompt` ve isteğe bağlı konuşma geçmişi (`history`) göndermenize olanak tanır. Yanıt, **Server-Sent Events (SSE)** formatında `text/event-stream` olarak akar — tüm yanıtın bitmesi beklenmez, token'lar geldikçe işlenebilir.

## İş kuralları

<Note>
  **`history` alanı:** Önceki konuşma bağlamını aktarmak için kullanılır. Maksimum **20 mesaj** gönderilebilir. Her mesaj `role` (`user` veya `assistant`) ve `content` alanlarını içermelidir.
</Note>

<Warning>
  **`prompt` limiti:** Minimum 1, maksimum **2000 karakter**. Aşılırsa `422 Unprocessable Entity` döner.
</Warning>

## SSE Event akışı

Yanıt aşağıdaki sırayla event'ler gönderir:

| Event           | Açıklama                        | Data içeriği                              |
| --------------- | ------------------------------- | ----------------------------------------- |
| `stream_start`  | Stream açıldı                   | `model`, `provider`                       |
| `step_start`    | Adım başladı                    | —                                         |
| `text_start`    | Metin bloğu başladı             | `message_id`                              |
| `text_delta`    | Token chunk geldi (asıl içerik) | `delta` (metin parçası), `message_id`     |
| `text_complete` | Metin bloğu tamamlandı          | `message_id`                              |
| `step_finish`   | Adım bitti                      | —                                         |
| `stream_end`    | Stream kapandı                  | `finish_reason`, `usage` (token sayıları) |

<Tip>
  İstemci tarafında gerçek zamanlı metin göstermek için `text_delta` event'lerini dinleyin ve `delta` alanını birleştirin. Stream bittikten sonra `stream_end` içindeki `usage` ile token tüketimini takip edebilirsiniz.
</Tip>

## Yetkilendirme

<Note>
  FlexyChat endpoint'inde rol tabanlı izin kontrolü (`ViewAny:Resource` vb.) **uygulanmaz** — erişim kontrolü tamamen token scope + throttle seviyesindedir. `middleware('tenant')` gerektirdiğinden aktif bir tenant bağlamı zorunludur.
</Note>

### Token scope'ları (Passport)

| İşlem                | Scope              |
| -------------------- | ------------------ |
| Streaming (`stream`) | `flexy_chat:write` |

<Note>
  `flexy_chat:read` scope'u **yoktur** — yalnızca `flexy_chat:write` kullanılır.
</Note>

### Throttle

| Throttle              | Endpoint                  | Açıklama                                |
| --------------------- | ------------------------- | --------------------------------------- |
| `throttle:flexy-chat` | `POST /flexy-chat/stream` | FlexyChat'e özgü özel rate limit kuralı |