openapi: 3.2.0
info:
  version: 1.0.0
  title: Swagger Sessions API
servers:
- url: https://api.siro.ai/
  description: Siro API Gateway
tags:
- name: Sessions
paths:
  /v1/sessions:
    get:
      summary: List past chat sessions for the authenticated user.
      description: Returns session metadata (sessionId, title, createdAt, updatedAt, sourceSystem) ordered by most recent first. sourceSystem is AIF or AURORA -- Aurora conversations are read-only. Supports cursor-based pagination. Pass organizationId to scope results to a specific org (for org switchers).
      parameters:
      - schema:
          type: string
        required: false
        name: cursor
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        required: false
        name: limit
        in: query
      - schema:
          type: string
        required: false
        name: organizationId
        in: query
      responses:
        '200':
          description: List past chat sessions for the authenticated user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sessions:
                        type: array
                        items:
                          type: object
                          properties:
                            sessionId:
                              type: string
                            title:
                              type: string
                            createdAt:
                              type: string
                              format: date-time
                            updatedAt:
                              type: string
                              format: date-time
                            sourceSystem:
                              type: string
                              enum:
                              - AIF
                              - AURORA
                          required:
                          - sessionId
                          - title
                          - createdAt
                          - updatedAt
                          - sourceSystem
                      nextCursor:
                        type: string
                    required:
                    - sessions
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Sessions
  /v1/sessions/{sessionId}:
    get:
      summary: Get full message history for a chat session.
      description: Validates ownership, then returns the full ChatMessage history for the session as Q&A message pairs. Each model row includes invocationId (feedback key) and persisted feedback when set. sourceSystem indicates AIF vs AURORA (Aurora conversations are read-only).
      responses:
        '200':
          description: Get full message history for a chat session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sessionId:
                        type: string
                      title:
                        type: string
                      messages:
                        type: array
                        items:
                          oneOf:
                          - type: object
                            properties:
                              role:
                                type: string
                                enum:
                                - user
                              parts:
                                type: array
                                items:
                                  oneOf:
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - text
                                      text:
                                        type: string
                                    required:
                                    - kind
                                    - text
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - tool
                                      tool:
                                        type: string
                                        enum:
                                        - show_chart
                                      data: {}
                                    required:
                                    - kind
                                    - tool
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - markdown-patch
                                      patches:
                                        type: array
                                        items: {}
                                      seq:
                                        type: integer
                                        minimum: 0
                                      segment:
                                        type: integer
                                        minimum: 0
                                    required:
                                    - kind
                                    - patches
                                    - seq
                                    - segment
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - markdown-tokens
                                      tokens:
                                        type: array
                                        items: {}
                                      segment:
                                        type: integer
                                        minimum: 0
                                      intermediate:
                                        type: boolean
                                    required:
                                    - kind
                                    - tokens
                                    - segment
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - segment-meta
                                      segment:
                                        type: integer
                                        minimum: 0
                                      intermediate:
                                        type: boolean
                                    required:
                                    - kind
                                    - segment
                                    - intermediate
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - halftime-report
                                      sections:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            id:
                                              type: string
                                              description: ID of the Halftime report topic
                                            title:
                                              type: string
                                              description: Name of the Halftime report topic
                                            guidance:
                                              type: string
                                              description: Guidance generated for Halftime report topic
                                          required:
                                          - id
                                          - title
                                          - guidance
                                    required:
                                    - kind
                                    - sections
                            required:
                            - role
                            - parts
                          - type: object
                            properties:
                              role:
                                type: string
                                enum:
                                - model
                              parts:
                                type: array
                                items:
                                  oneOf:
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - text
                                      text:
                                        type: string
                                    required:
                                    - kind
                                    - text
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - tool
                                      tool:
                                        type: string
                                        enum:
                                        - show_chart
                                      data: {}
                                    required:
                                    - kind
                                    - tool
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - markdown-patch
                                      patches:
                                        type: array
                                        items: {}
                                      seq:
                                        type: integer
                                        minimum: 0
                                      segment:
                                        type: integer
                                        minimum: 0
                                    required:
                                    - kind
                                    - patches
                                    - seq
                                    - segment
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - markdown-tokens
                                      tokens:
                                        type: array
                                        items: {}
                                      segment:
                                        type: integer
                                        minimum: 0
                                      intermediate:
                                        type: boolean
                                    required:
                                    - kind
                                    - tokens
                                    - segment
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - segment-meta
                                      segment:
                                        type: integer
                                        minimum: 0
                                      intermediate:
                                        type: boolean
                                    required:
                                    - kind
                                    - segment
                                    - intermediate
                                  - type: object
                                    properties:
                                      kind:
                                        type: string
                                        enum:
                                        - halftime-report
                                      sections:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            id:
                                              type: string
                                              description: ID of the Halftime report topic
                                            title:
                                              type: string
                                              description: Name of the Halftime report topic
                                            guidance:
                                              type: string
                                              description: Guidance generated for Halftime report topic
                                          required:
                                          - id
                                          - title
                                          - guidance
                                    required:
                                    - kind
                                    - sections
                              invocationId:
                                type: string
                              feedback:
                                type:
                                - string
                                - 'null'
                                enum:
                                - thumbs_up
                                - thumbs_down
                              feedbackText:
                                type: string
                                maxLength: 1000
                            required:
                            - role
                            - parts
                            - feedback
                      sourceSystem:
                        type: string
                        enum:
                        - AIF
                        - AURORA
                    required:
                    - sessionId
                    - title
                    - messages
                    - sourceSystem
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Sessions
    patch:
      summary: Rename a chat session.
      description: Updates the chat session title.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 500
              required:
              - title
      responses:
        '200':
          description: Rename a chat session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sessionId:
                        type: string
                      title:
                        type: string
                    required:
                    - sessionId
                    - title
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Sessions
    delete:
      summary: Delete a chat session.
      description: Soft-deletes the chat session.
      responses:
        '200':
          description: Delete a chat session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sessionId:
                        type: string
                    required:
                    - sessionId
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Sessions
  /v1/sessions/{sessionId}/invocations/{invocationId}/feedback:
    patch:
      summary: Upsert thumbs feedback for an ADK turn (invocation).
      description: Stores or replaces feedback for the given ADK invocation id within a session the caller owns.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                feedback:
                  type:
                  - string
                  - 'null'
                  enum:
                  - thumbs_up
                  - thumbs_down
                feedbackText:
                  type: string
                  maxLength: 1000
              required:
              - feedback
      responses:
        '200':
          description: Upsert thumbs feedback for an ADK turn (invocation).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sessionId:
                        type: string
                      invocationId:
                        type: string
                      feedback:
                        type:
                        - string
                        - 'null'
                        enum:
                        - thumbs_up
                        - thumbs_down
                      feedbackText:
                        type: string
                        maxLength: 1000
                    required:
                    - sessionId
                    - invocationId
                    - feedback
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Sessions
  /v1/sessions/{sessionId}/messages/{messageId}/feedback:
    patch:
      summary: Upsert thumbs feedback for a chat message.
      description: Stores or replaces feedback on a MODEL ChatMessage row (by message id) within a session the caller owns. Successor to the invocation-keyed feedback route; requires the session to exist in the unified chat tables.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                feedback:
                  type:
                  - string
                  - 'null'
                  enum:
                  - thumbs_up
                  - thumbs_down
                feedbackText:
                  type: string
                  maxLength: 1000
              required:
              - feedback
      responses:
        '200':
          description: Upsert thumbs feedback for a chat message.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sessionId:
                        type: string
                      messageId:
                        type: string
                      feedback:
                        type:
                        - string
                        - 'null'
                        enum:
                        - thumbs_up
                        - thumbs_down
                      feedbackText:
                        type: string
                        maxLength: 1000
                    required:
                    - sessionId
                    - messageId
                    - feedback
                  cursor:
                    anyOf:
                    - type: string
                    - type: number
                    - {}
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type:
                    - number
                    - 'null'
                  hasNextPage:
                    type: boolean
                required:
                - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                        message:
                          type: string
                      required:
                      - code
                      - path
                      - message
                  name:
                    type: string
                    enum:
                    - ZodError
                required:
                - issues
                - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                - error
      security:
      - SiroAuthToken: []
      tags:
      - Sessions
components:
  securitySchemes:
    SiroAuthToken:
      type: apiKey
      in: header
      name: x-siro-auth-token
      description: 'OAuth access token for user-scoped requests (Authorization Code or machine-to-machine). Send header `x-siro-auth-token: <oauth-access-token>`. Not an organization API key.'
      x-default: <oauth-access-token>
externalDocs:
  description: View the raw OpenAPI Specification in JSON format
  url: /swagger.json