openapi: 3.0.3
info:
  title: Liya AI — OpenAI Uyumlu API
  description: |
    Liya AI platformu için OpenAI uyumlu REST API.

    Liya AI asistanlarını, OpenAI Chat Completions API'sini doğal olarak destekleyen uygulamalara (AnythingLLM, OpenClaw, LangChain vb.) entegre etmek için bu API'yi kullanın.

    ## Kimlik Doğrulama (Authentication)
    Liya AI API anahtarınızı `Authorization` başlığında belirtin:

    ```
    Authorization: Bearer liwhai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ```

    API anahtarınız `liwhai_` öneki ile başlar. Liya AI Dashboard → Projects → API Keys bölümünden oluşturabilirsiniz.

    ## Temel URL (Base URL)
    AnythingLLM ve benzeri araçlarda **Base URL** olarak aşağıdaki adresi kullanın:

    ```
    https://app-{X}-ai.liyalabs.com/api/v1/openai/v1
    ```

    > ℹ️ `/v1` son eki **zorunludur**. AnythingLLM, OpenAI SDK, LangChain ve
    > LlamaIndex gibi araçlar base URL'in sonuna `/chat/completions` ve
    > `/models` ekler — bu OpenAI standardıdır (LM Studio, vLLM, llama.cpp
    > aynı kuralı izler).
    >
    > Eski `/v1` öneksiz yollar
    > (`/api/v1/openai/chat/completions`, `/api/v1/openai/models`) hâlâ
    > çalışır ancak yeni entegrasyonlar için önerilmez.

    ## Desteklenen Uç Noktalar
    | Method | Path | Açıklama |
    |--------|------|----------|
    | POST | `/api/v1/openai/v1/chat/completions` | Sohbet tamamlama (OpenAI formatı) |
    | GET  | `/api/v1/openai/v1/models`           | Asistanları OpenAI modelleri olarak listele |
    | GET  | `/api/v1/openai`                     | Bağlantı testi (auth gerektirmez) |

    ## Model Adı
    `model` alanına Liya AI asistanınızın UUID'sini girin.
    `GET /api/v1/openai/v1/models` endpoint'i aktif asistanlarınızı otomatik listeler.

    ## AnythingLLM ile Kurulum

    1. AnythingLLM → **Settings** → **AI Providers** → **Generic OpenAI** (veya Custom OpenAI)
    2. **Base URL:** `https://app-{X}-ai.liyalabs.com/api/v1/openai/v1`
    3. **API Key:** `liwhai_` ile başlayan Liya AI API anahtarınız
    4. **Model Name:** Asistan UUID'niz — `GET /api/v1/openai/v1/models` ile listeleyebilirsiniz
    5. **"Load Models"** veya **"Test Connection"** butonuna basarak doğrulayın

    ## Uyumluluk
    Bu uç nokta, standart OpenAI `ChatCompletion` nesne yapısını uygular.
    Token kullanımı, hesabınızın fiyatlandırma katmanına göre takip edilir.

  version: 0.2.0
  contact:
    name: Liya Labs Destek
    url: https://liyalabs.com
    email: support@liyalabs.com

servers:
  - url: https://app-{X}-ai.liyalabs.com
    description: |
      {X} yerine proje instance kimliğinizi yazın.
      Base URL olarak kullanılacak tam adres: https://app-{X}-ai.liyalabs.com/api/v1/openai/v1
    variables:
      X:
        default: "1"
        description: Proje instance numarası

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: LiyaAI-ApiKey
      description: |
        `liwhai_` öneki ile başlayan Liya AI API anahtarı.
        Örnek: `Authorization: Bearer liwhai_abc123...`

  schemas:
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [system, user, assistant]
          description: Mesaj rolü
        content:
          type: string
          description: Mesaj içeriği

    ChatCompletionRequest:
      type: object
      required:
        - messages
      properties:
        model:
          type: string
          description: |
            Liya AI asistanınızın UUID'si.
            Örnek: `550e8400-e29b-41d4-a716-446655440000`
            Boş bırakılırsa projenin ilk aktif asistanı kullanılır.
          example: "550e8400-e29b-41d4-a716-446655440000"
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          minimum: 0.0
          maximum: 2.0
          description: Örnekleme sıcaklığı (şu an iletilmez, kabul edilir)
        max_tokens:
          type: integer
          minimum: 1
          description: Maksimum token sayısı (şu an iletilmez, kabul edilir)
        stream:
          type: boolean
          default: false
          description: Akış modu (şu an desteklenmiyor, false olmalı)

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          example: "chatcmpl-abc123"
        object:
          type: string
          example: "chat.completion"
        created:
          type: integer
          example: 1720000000
        model:
          type: string
          description: Yanıtı üreten asistan UUID'si
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
                example: "stop"
              logprobs:
                nullable: true
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer

    ModelObject:
      type: object
      properties:
        id:
          type: string
          description: Asistan UUID'si (model adı olarak kullanılır)
          example: "550e8400-e29b-41d4-a716-446655440000"
        object:
          type: string
          example: "model"
        created:
          type: integer
        owned_by:
          type: string
          example: "liya-ai"
        display_name:
          type: string
          description: İnsan okunabilir asistan adı
        description:
          type: string

    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string

paths:
  /api/v1/openai/v1/chat/completions:
    post:
      summary: Sohbet tamamlaması oluştur
      operationId: createChatCompletion
      description: |
        OpenAI `ChatCompletion` formatında yanıt üretir.

        **Eski yol:** `POST /api/v1/openai/chat/completions` (sondaki `/v1`
        olmadan) mevcut entegrasyonlar için hâlâ çalışır ancak yeni
        entegrasyonlar için önerilmez.
      tags:
        - Chat
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: "550e8400-e29b-41d4-a716-446655440000"
              messages:
                - role: "user"
                  content: "Merhaba, nasıl yardımcı olabilirsin?"
      responses:
        '200':
          description: Başarılı yanıt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '401':
          description: Geçersiz veya eksik API anahtarı
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: "Invalid API Key."
                  type: "invalid_request_error"
                  code: "invalid_api_key"
        '402':
          description: Yetersiz bakiye
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Asistan bulunamadı
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: "No active assistant found for this project."
                  type: "invalid_request_error"
                  code: "model_not_found"

  /api/v1/openai/v1/models:
    get:
      summary: Kullanılabilir asistanları listele
      operationId: listModels
      description: |
        Projenize ait aktif asistanları OpenAI model listesi formatında döndürür.
        AnythingLLM bu endpoint'i "Load Models" butonuyla otomatik çağırır.

        **Eski yol:** `GET /api/v1/openai/models` (sondaki `/v1` olmadan)
        mevcut entegrasyonlar için hâlâ çalışır ancak önerilmez.
      tags:
        - Models
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Model listesi
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    example: "list"
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ModelObject'
              example:
                object: "list"
                data:
                  - id: "550e8400-e29b-41d4-a716-446655440000"
                    object: "model"
                    created: 1720000000
                    owned_by: "liya-ai"
                    display_name: "Müşteri Destek Asistanı"
                    description: "Ürün destek soruları için"
        '401':
          description: Geçersiz veya eksik API anahtarı
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
