openapi: 3.1.0
info:
  # Do not change the title, if the title changes, the import paths will be broken
  title: Api
  version: 0.1.0
  description: AI Dev Platform API
servers:
  - url: /api
    description: Base API path
tags:
  - name: health
    description: Health operations
  - name: projects
    description: Project management
  - name: conversations
    description: AI conversation management
paths:
  /healthz:
    get:
      operationId: healthCheck
      tags: [health]
      summary: Health check
      description: Returns server health status
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

  /projects:
    get:
      operationId: listProjects
      tags: [projects]
      summary: List all projects
      responses:
        "200":
          description: List of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Project"
    post:
      operationId: createProject
      tags: [projects]
      summary: Create a new project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectInput"
      responses:
        "201":
          description: Created project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"

  /projects/{id}:
    get:
      operationId: getProject
      tags: [projects]
      summary: Get a project
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    patch:
      operationId: updateProject
      tags: [projects]
      summary: Update a project
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProjectUpdate"
      responses:
        "200":
          description: Updated project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    delete:
      operationId: deleteProject
      tags: [projects]
      summary: Delete a project
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: Deleted
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"

  /projects/stats:
    get:
      operationId: getProjectStats
      tags: [projects]
      summary: Get project statistics
      responses:
        "200":
          description: Project stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectStats"

  /conversations:
    get:
      operationId: listConversations
      tags: [conversations]
      summary: List all conversations
      responses:
        "200":
          description: List of conversations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Conversation"
    post:
      operationId: createConversation
      tags: [conversations]
      summary: Create a new conversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConversationInput"
      responses:
        "201":
          description: Created conversation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Conversation"

  /conversations/{id}:
    get:
      operationId: getConversation
      tags: [conversations]
      summary: Get conversation with messages
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Conversation with messages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConversationWithMessages"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
    delete:
      operationId: deleteConversation
      tags: [conversations]
      summary: Delete a conversation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: Deleted
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"

  /conversations/{id}/messages:
    get:
      operationId: listMessages
      tags: [conversations]
      summary: List messages in a conversation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Messages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Message"
    post:
      operationId: sendMessage
      tags: [conversations]
      summary: Send a message and stream AI response
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessageInput"
      responses:
        "200":
          description: SSE stream of AI response chunks
          content:
            text/event-stream: {}

components:
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
      required:
        - status

    ApiError:
      type: object
      properties:
        error:
          type: string
      required:
        - error

    Project:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: ["string", "null"]
        status:
          type: string
          enum: [active, archived]
        conversationCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - status
        - conversationCount
        - createdAt
        - updatedAt

    ProjectInput:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string
      required:
        - name

    ProjectUpdate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string
        status:
          type: string
          enum: [active, archived]

    ProjectStats:
      type: object
      properties:
        totalProjects:
          type: integer
        activeProjects:
          type: integer
        totalConversations:
          type: integer
        totalMessages:
          type: integer
      required:
        - totalProjects
        - activeProjects
        - totalConversations
        - totalMessages

    Conversation:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        projectId:
          type: ["integer", "null"]
        model:
          type: string
        messageCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - title
        - model
        - messageCount
        - createdAt
        - updatedAt

    ConversationInput:
      type: object
      properties:
        title:
          type: string
          minLength: 1
        projectId:
          type: integer
        model:
          type: string
      required:
        - title

    ConversationWithMessages:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        projectId:
          type: ["integer", "null"]
        model:
          type: string
        messageCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        messages:
          type: array
          items:
            $ref: "#/components/schemas/Message"
      required:
        - id
        - title
        - model
        - messageCount
        - createdAt
        - updatedAt
        - messages

    Message:
      type: object
      properties:
        id:
          type: integer
        conversationId:
          type: integer
        role:
          type: string
          enum: [user, assistant, system]
        content:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - conversationId
        - role
        - content
        - createdAt

    MessageInput:
      type: object
      properties:
        content:
          type: string
          minLength: 1
        model:
          type: string
      required:
        - content
