ss-tools/specs/021-llm-project-assistant/contracts/assistant-api.openapi.yaml

openapi: 3.0.3
info:
  title: Assistant Chat API
  version: 1.0.0
  description: API contract for LLM chat assistant command orchestration.

servers:
  - url: /api

paths:
  /assistant/messages:
    post:
      summary: Send user message to assistant
      description: Parses command, applies safety checks, and returns assistant response state.
      operationId: sendAssistantMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantMessageRequest'
      responses:
        '200':
          description: Assistant response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantMessageResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden

  /assistant/confirmations/{confirmation_id}/confirm:
    post:
      summary: Confirm dangerous operation
      description: Confirms one pending risky command and executes it once.
      operationId: confirmAssistantOperation
      parameters:
        - in: path
          name: confirmation_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Confirmation handled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantMessageResponse'
        '400':
          description: Invalid or expired confirmation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Confirmation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /assistant/confirmations/{confirmation_id}/cancel:
    post:
      summary: Cancel dangerous operation
      description: Cancels pending confirmation and prevents execution.
      operationId: cancelAssistantOperation
      parameters:
        - in: path
          name: confirmation_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Confirmation cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantMessageResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Confirmation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /assistant/history:
    get:
      summary: Get assistant conversation history
      description: Returns paginated history for current user.
      operationId: getAssistantHistory
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            minimum: 1
            default: 1
        - in: query
          name: page_size
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        '200':
          description: Conversation history page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantHistoryPage'
        '401':
          description: Unauthorized

components:
  schemas:
    AssistantResponseState:
      type: string
      enum:
        - started
        - success
        - failed
        - denied
        - needs_confirmation
        - needs_clarification

    RiskLevel:
      type: string
      enum:
        - safe
        - guarded
        - dangerous

    CommandIntent:
      type: object
      properties:
        domain:
          type: string
        operation:
          type: string
        entities:
          type: object
          additionalProperties: true
        confidence:
          type: number
          minimum: 0
          maximum: 1
        risk_level:
          $ref: '#/components/schemas/RiskLevel'
      required: [domain, operation, confidence, risk_level]

    AssistantMessageRequest:
      type: object
      properties:
        conversation_id:
          type: string
          nullable: true
        message:
          type: string
          minLength: 1
          maxLength: 4000
      required: [message]

    AssistantAction:
      type: object
      properties:
        type:
          type: string
          enum: [confirm, cancel, open_task, open_reports, rephrase]
        label:
          type: string
        target:
          type: string
          nullable: true
      required: [type, label]

    AssistantMessageResponse:
      type: object
      properties:
        conversation_id:
          type: string
        response_id:
          type: string
        state:
          $ref: '#/components/schemas/AssistantResponseState'
        text:
          type: string
        intent:
          $ref: '#/components/schemas/CommandIntent'
        confirmation_id:
          type: string
          nullable: true
        task_id:
          type: string
          nullable: true
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AssistantAction'
        created_at:
          type: string
          format: date-time
      required: [conversation_id, response_id, state, text, created_at]

    AssistantMessage:
      type: object
      properties:
        message_id:
          type: string
        conversation_id:
          type: string
        role:
          type: string
          enum: [user, assistant]
        text:
          type: string
        state:
          $ref: '#/components/schemas/AssistantResponseState'
        task_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
      required: [message_id, conversation_id, role, text, created_at]

    AssistantHistoryPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AssistantMessage'
        total:
          type: integer
          minimum: 0
        page:
          type: integer
          minimum: 1
        page_size:
          type: integer
          minimum: 1
        has_next:
          type: boolean
      required: [items, total, page, page_size, has_next]

    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
      required: [detail]