openapi.yaml

openapi: 3.0.3
info:
    title: Chat API
    description: |
        REST API for chat interactions with an AI agent.

        ## WebSocket Endpoint

        In addition to the REST API, a WebSocket endpoint is available for real-time bidirectional communication:

        **Endpoint:** `ws://localhost:8080/ws/chat`

        **Headers:**
        - `X-Session-ID` (optional): Session identifier for maintaining conversation context. If not provided, a new session will be created.

        **Message Format:**
        - **Send (Client → Server):** JSON matching the `ChatRequest` schema (without sessionId field)
        - **Receive (Server → Client):** JSON matching the `Answer` schema (without sessionId field)

        **Example:**
        ```javascript
        const ws = new WebSocket('ws://localhost:8080/ws/chat', {
          headers: {
            'X-Session-ID': '550e8400-e29b-41d4-a716-446655440000'  // Optional
          }
        });

        ws.onopen = () => {
          ws.send(JSON.stringify({
            message: "Hello!"
          }));
        };

        ws.onmessage = (event) => {
          const answer = JSON.parse(event.data);
          console.log(answer.message);
        };
        ```

        **Note:** Session ID is managed via the `X-Session-ID` header during the WebSocket handshake, not in the message payload.
    version: 1.0.0
servers:
    -   url: http://localhost:8080
        description: Local development server
paths:
    /api/version:
        get:
            summary: Get API version
            description: Returns the current version of the API
            operationId: getVersion
            tags:
                - chat
            responses:
                '200':
                    description: API version
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "1.0"
    /api/chat:
        post:
            summary: Send a chat message
            description: Sends a message to the AI agent and receives a response
            operationId: chat
            tags:
                - chat
            parameters:
                -   $ref: '#/components/parameters/SessionIdParam'
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ChatRequest'
            responses:
                '200':
                    description: Chat response
                    headers:
                        X-Session-ID:
                            $ref: '#/components/headers/SessionIdHeader'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Answer'
    /api/koog/strategy/graph:
        get:
            summary: Get strategy graph diagram
            description: Returns a Mermaid diagram text representation of the strategy graph
            operationId: getStrategyGraph
            tags:
                - koog
            responses:
                '200':
                    description: Mermaid diagram text for strategy graph
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "graph TD\n    A[Strategy] --> B[Implementation]\n    B --> C[Results]"
components:
    parameters:
        SessionIdParam:
            name: X-Session-ID
            in: header
            description: Optional session identifier for maintaining conversation context. If not provided, a new session will be created.
            required: false
            schema:
                $ref: '#/components/schemas/ChatSessionId'
    headers:
        SessionIdHeader:
            description: Session identifier for the conversation
            schema:
                $ref: '#/components/schemas/ChatSessionId'
    schemas:
        ChatSessionId:
            description: Chat Session identifier  for the conversation
            type: string
            pattern: '^[_0-9a-zA-Z-]{1,64}$'
            example: "550e8400-e29b-41d4-a716-446655440000"
        ChatRequestId:
            description: Chat Request identifier
            pattern: '^[_0-9a-zA-Z-]{1,64}$'
            type: string
        ChatRequest:
            type: object
            required:
                - message
            properties:
                chatRequestId:
                    $ref: '#/components/schemas/ChatRequestId'
                chatSessionId:
                    $ref: '#/components/schemas/ChatSessionId'
                message:
                    type: string
                    description: The message to send to the AI agent
                    example: "How do I implement a REST API in Spring Boot?"
                streaming:
                    type: boolean
                    default: false
        Answer:
            type: object
            required:
                - message
                - chatSessionId
                - completed
            properties:
                message:
                    type: string
                    description: The AI agent's response
                    example: "To implement a REST API in Spring Boot, you can use @RestController..."
                chatSessionId:
                    $ref: '#/components/schemas/ChatSessionId'
                chatRequestId:
                    $ref: '#/components/schemas/ChatRequestId'
                completed:
                    type: boolean
                    description: Is response complete