{
  "openapi": "3.1.0",
  "info": {
    "title": "argemas Chat API",
    "description": "Restricted RAG chatbot endpoint that powers the authenticated chat widget on the argemas marketing site. Access is gated by NextAuth Google OAuth and a server-side email whitelist (ALLOWED_EMAILS / ALLOWED_DOMAINS env vars). This is NOT a public API.",
    "version": "1.0.0",
    "contact": {
      "name": "Arge Bilisim",
      "url": "https://argebilisim.com/iletisim"
    }
  },
  "servers": [
    { "url": "https://argebilisim.com" }
  ],
  "paths": {
    "/api/chat": {
      "post": {
        "summary": "Query the RAG chatbot",
        "description": "Forwards the user query (plus optional history) to an upstream RAG backend and returns the generated answer with optional source citations. Requires an authenticated NextAuth session whose email is on the whitelist. Upstream backend failures are surfaced as HTTP 200 with a Turkish error message inside the `response` field (see description in the schema).",
        "operationId": "postChat",
        "security": [
          { "nextauthSessionCookie": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful RAG response, OR a graceful fallback message when the upstream RAG backend is unavailable (the handler intentionally masks upstream 5xx as 200 with a Turkish user-facing message).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatResponse" }
              }
            }
          },
          "400": {
            "description": "Missing or invalid `query` field.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "No authenticated NextAuth session.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "403": {
            "description": "Authenticated user but email is not on the whitelist. In practice the NextAuth `signIn` callback rejects sign-in before a session is issued, so unauthorized users typically see 401 at this endpoint rather than 403."
          },
          "500": {
            "description": "Unhandled server error. The current handler catches errors and returns HTTP 200 with a Turkish fallback `response`, so 500 is reserved for future strict-mode behavior."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "nextauthSessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "next-auth.session-token",
        "description": "NextAuth session cookie issued after Google OAuth sign-in at /api/auth/signin. On production the cookie name is `__Secure-next-auth.session-token`. Only Google accounts whose email appears in the ALLOWED_EMAILS env var (or whose domain appears in ALLOWED_DOMAINS) are permitted to obtain a session."
      }
    },
    "schemas": {
      "ChatMessage": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {
            "type": "string",
            "enum": ["user", "assistant"]
          },
          "content": { "type": "string" }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string",
            "description": "User's question in natural language (Turkish or English)."
          },
          "history": {
            "type": "array",
            "description": "Prior turns of the conversation, oldest first. Optional.",
            "items": { "$ref": "#/components/schemas/ChatMessage" }
          }
        }
      },
      "ChatSource": {
        "type": "object",
        "required": ["source", "title", "chunk_index", "total_chunks"],
        "properties": {
          "source": { "type": "string" },
          "title": { "type": "string" },
          "chunk_index": { "type": "integer" },
          "total_chunks": { "type": "integer" }
        }
      },
      "ChatResponse": {
        "type": "object",
        "required": ["response"],
        "properties": {
          "response": {
            "type": "string",
            "description": "Generated answer from the RAG backend, or a Turkish fallback message when the backend is unreachable."
          },
          "sources": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ChatSource" }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" }
        }
      }
    }
  }
}