openapi: 3.1.0
info:
  title: Hermes Agent Gateway API
  description: >
    Production Reverse Proxy API for Hermes Agent Gateway.
    Secured behind a timing-safe Auth Key barrier and designed for integration with
    external chat applications, mobile frontends, and autonomous AI agents.
  version: 1.0.0
servers:
  - url: https://{cloudflare_domain}:{port}
    description: Public Cloudflare Reverse Proxy (HTTPS Port Forwarding)
    variables:
      cloudflare_domain:
        default: hermes.yourdomain.com
        description: Cloudflare proxied hostname
      port:
        default: "8443"
        description: Forwarded WAN port (e.g. 8443 or 443)
  - url: http://localhost:8643
    description: Local Direct Reverse Proxy

security:
  - BearerAuth: []
  - ApiKeyAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: "Supply proxy auth key via Authorization: Bearer <AUTH_KEY>"
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "Supply proxy auth key via X-API-Key: <AUTH_KEY>"

  schemas:
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum: [system, user, assistant, tool]
          description: Message author role
        content:
          type: string
          description: Message body text
        name:
          type: string
          description: Optional author or tool name

    ChatCompletionRequest:
      type: object
      required:
        - messages
      properties:
        model:
          type: string
          default: "auto"
          description: Model identifier or alias (defaults to gateway configured active model)
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          default: false
          description: Enable Server-Sent Events (SSE) streaming
        temperature:
          type: number
          default: 0.7
        max_tokens:
          type: integer
          description: Optional completion token limit

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
                example: stop
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer

    SessionCreateRequest:
      type: object
      properties:
        title:
          type: string
          description: Optional descriptive session title
        model:
          type: string
          description: Model override for this session

    SessionChatStreamRequest:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: User prompt or message to send to Hermes
        model:
          type: string
          description: Optional model override

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

paths:
  /health:
    get:
      summary: Health Check
      description: Returns liveness status of the reverse proxy (publicly accessible).
      security: []
      responses:
        '200':
          description: Proxy healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  proxy:
                    type: string
                    example: nginx
                  port:
                    type: integer
                    example: 8643

  /v1/chat/completions:
    post:
      summary: OpenAI-Compatible Chat Completions
      description: >
        Primary endpoint for chat app integration. Compatible with the official OpenAI SDK
        in Python, TypeScript, Go, etc. When stream is true, responses are streamed as
        standard text/event-stream Server-Sent Events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: Successful completion (non-streaming JSON or streaming SSE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: "Chunked SSE stream (data: {\"choices\":[{\"delta\":{\"content\":\"...\"}}]})"
        '401':
          description: Missing or invalid proxy auth key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/models:
    get:
      summary: List Models
      description: Returns list of available models and aliases configured in Hermes Gateway.
      responses:
        '200':
          description: List of models
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    example: list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        object:
                          type: string
                          example: model

  /api/sessions:
    get:
      summary: List Conversation Sessions
      description: Retrieves ongoing and archived conversation sessions.
      responses:
        '200':
          description: Array of session summaries
    post:
      summary: Create New Session
      description: Creates an isolated conversation session in Hermes Gateway.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreateRequest'
      responses:
        '201':
          description: Session created

  /api/sessions/{session_id}/messages:
    get:
      summary: Get Session Message History
      description: Returns all previous turns, tool executions, and assistant responses for a session.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Conversation history

  /api/sessions/{session_id}/chat/stream:
    post:
      summary: Native Hermes Chat Stream
      description: >
        Dispatches a user turn in an existing session and streams raw assistant output,
        including live tool calls and reasoning events, via Server-Sent Events.
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionChatStreamRequest'
      responses:
        '200':
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string