openapi: 3.0.3
info:
  title: IrisAgent's API Reference
  description: |
    IrisAgent service can be used as an API to power intelligent conversations and search, index, and connect with your internal and external knowledge articles, tickets, community forums, product documentation,
    and other informational content.
  version: 1.2.0
servers:
  - url: 'https://api1.irisagent.com'
paths:
  /v1/irisgpt/ask:
    post:
      operationId: irisgptAsk
      summary: |
        Get AI answer to any query
      description: |
        Get an AI answer to any support query using the trained information such as knowledge articles, tickets, documentation, and more.
      parameters:
        - $ref: '#/components/parameters/LanguageIsoCode'
        - $ref: '#/components/parameters/ChatIdentifier'
      requestBody:
        description: |
          The `requestBody` contains the information sent to IrisGPT for processing.
          The main component is the `query`, representing the user's input or question.
          This body must be sent in JSON format.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          $ref: '#/components/responses/AskResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '408':
          $ref: '#/components/responses/408'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
  /v1/summary:
    post:
      operationId: summarizeConversation
      summary: Get summary
      description: Get an AI-powered summary of your support conversation or ticket
      parameters:
        - $ref: '#/components/parameters/LanguageIsoCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SummaryRequest'
      responses:
        '200':
          $ref: '#/components/responses/SummaryResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '408':
          $ref: '#/components/responses/408'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
  /v1/feedback:
    post:
      operationId: postFeedback
      summary: Send user feedback
      description: Send user or agent feedback on IrisGPT AI answers via this API. This feedback helps IrisAgent improve the quality of its responses over time.
      parameters:
        - $ref: '#/components/parameters/ChatIdentifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackRequest'
      responses:
        '200':
          description: Feedback submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '408':
          $ref: '#/components/responses/408'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
  /v1/tag:
    post:
      operationId: autoTag
      summary: Get AI-powered tag
      description: Get AI-powered tag(s) for a support conversation using pre-built AI models
      parameters:
        - $ref: '#/components/parameters/LanguageIsoCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagRequest'
      responses:
        '200':
          $ref: '#/components/responses/TagResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '408':
          $ref: '#/components/responses/408'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
  /v1/sentiment:
    post:
      operationId: analyzeSentiment
      summary: Get sentiment
      description: Get AI-powered sentiment analysis for a support conversation
      parameters:
        - $ref: '#/components/parameters/LanguageIsoCode'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SentimentRequest'
      responses:
        '200':
          $ref: '#/components/responses/SentimentResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '408':
          $ref: '#/components/responses/408'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
  /v1/articles:
    post:
      operationId: uploadArticles
      summary: Upload articles
      description: Send knowledge base articles for AI training via this API
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticlesUploadRequest'
      responses:
        '200':
          description: Articles uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized - invalid credentials
        '403':
          description: Forbidden - insufficient permissions
    delete:
      operationId: deleteArticles
      summary: Delete articles
      description: Send a request to delete knowledge base articles for AI training via this endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticlesDeleteRequest'
      responses:
        '200':
          description: Articles deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized - invalid credentials
        '403':
          description: Forbidden - insufficient permissions
  /v1/cases:
    post:
      operationId: uploadCases
      summary: Upload support cases
      description: Send support cases for AI training via this API
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CasesUploadRequest'
      responses:
        '200':
          description: Cases uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CasesUploadResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized - invalid credentials
        '403':
          description: Forbidden - insufficient permissions
  /v1/incidents:
    post:
      operationId: uploadIncidents
      summary: Upload incidents
      description: 'Send engineering, devops, or statuspage incidents for AI training via this endpoint'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncidentUploadRequest'
      responses:
        '201':
          description: Incident has been uploaded successfully
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized - invalid credentials
        '403':
          description: Forbidden - insufficient permissions
  /v1/search/cases:
    post:
      operationId: searchCases
      summary: Search cases
      description: |
        Search support cases using AI-powered recommendation. You can provide a search query, a conversationId to load ticket content, or both.
        At least one of query or conversationId must be provided. When both are provided, the ticket content is combined with the query for a richer search.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CasesSearchRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CasesSearchResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized - invalid credentials
        '403':
          description: Forbidden - insufficient permissions
        '404':
          description: Conversation not found - the specified conversationId does not exist
  /v1/community/search/articles:
    get:
      operationId: searchArticles
      summary: Search articles
      description: Search knowledge base articles for any query using AI-powered recommendation
      parameters:
        - name: text
          in: query
          description: The search query string.
          required: true
          schema:
            type: string
        - name: offset
          in: query
          description: Pagination offset for search results.
          required: false
          schema:
            type: integer
            format: uint
            minimum: 0
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
            format: uint
            default: 25
            minimum: 1
        - name: X-Business-Id
          in: header
          description: Business ID of the customer.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesSearchResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized - invalid credentials
        '403':
          description: Forbidden - insufficient permissions
components:
  parameters:
    ChatIdentifier:
      name: Chat-Identifier
      in: header
      description: |
        The `Chat-Identifier` is an optional header used to track the conversation session.
        If not provided, a new chat session will automatically be created.
        While not required for single request/response interactions, it is necessary for maintaining continuity in ongoing conversations.
      required: false
      schema:
        type: string
        format: uuid
    LanguageIsoCode:
      name: X-Language-Iso-Code
      in: header
      description: |
        This optional header allows you to specify the desired language.
        If not provided, automatic language detection will be used.
      schema:
        type: string
        format: iso-639-1
  schemas:
    Article:
      type: object
      properties:
        articleId:
          description: 'Unique article ID of the article, for example "article-01"'
          type: string
        url:
          description: Unique URL of the article
          type: string
          format: uri
        title:
          description: Title of the article
          type: string
        body:
          description: The full body of the article in markdown or HTML format
          type: string
        timeOfCreation:
          description: Epoch time in milliseconds of when the article was created
          type: integer
          format: int64
        timeLastPublished:
          description: Epoch time in milliseconds of when the article was last modified
          type: integer
          format: int64
        language:
          description: 'Language of the article in ISO 639-1 format (e.g., en, fr, de)'
          type: string
          format: iso-639-1
      required:
        - articleId
        - url
        - title
        - body
        - timeOfCreation
        - timeLastPublished
    DeleteArticle:
      type: object
      properties:
        articleId:
          description: 'Unique article ID of the article, for example "article-01"'
          type: string
      required:
        - articleId
    ArticlesResponse:
      type: object
      properties:
        result:
          type: string
          enum:
            - success
            - partial
      required:
        - result
    CaseComment:
      type: object
      properties:
        commentId:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        comment:
          type: string
          example: Please help to fix this ASAP.
        commenter:
          type: string
          example: Customer
        isPublic:
          type: boolean
          example: true
        timeOfCreation:
          description: Unix timestamp epoch in milli-seconds as string
          type: integer
          format: int64
          example: 17437722600
      required:
        - commentId
        - comment
        - commenter
        - timeOfCreation
    Case:
      type: object
      properties:
        id:
          type: string
          example: '12345'
        subject:
          type: string
          example: Application will not access the logs
        description:
          type: string
        status:
          type: string
          example: open
        priority:
          type: string
          example: high
        type:
          description: 'The type of case, such as Feature Request or Question'
          type: string
          x-go-type-skip-optional-pointer: true
        brand_id:
          description: The brand identifier associated with the case
          type: string
          x-go-type-skip-optional-pointer: true
        form_id:
          description: The form identifier associated with the case
          type: string
          x-go-type-skip-optional-pointer: true
        tags:
          type: array
          items:
            type: string
          example:
            - billing
            - urgent
          x-go-type-skip-optional-pointer: true
        timeOfCreation:
          description: Unix timestamp epoch in milli-seconds as string
          type: integer
          format: int64
          example: 17437722600
        comments:
          type: array
          items:
            $ref: '#/components/schemas/CaseComment'
          x-go-type-skip-optional-pointer: true
        url:
          description: Public link to the case
          type: string
          format: uri
          example: 'https://support.example.com/cases/12345'
        custom_fields:
          type: object
          example:
            department: IT
            priority_level: 1
          x-go-type-skip-optional-pointer: true
        kb_links:
          type: array
          items:
            type: string
            format: uri
        source:
          type: string
          example: email
        spam:
          description: Indicates if the case is marked as spam
          type: boolean
          example: false
      required:
        - id
        - subject
        - status
        - timeOfCreation
    CasesUploadResponse:
      type: object
      properties:
        result:
          type: string
          enum:
            - success
            - partial
      required:
        - result
    FeedbackResponse:
      type: object
      properties:
        result:
          type: string
          enum:
            - success
      required:
        - result
    FeedbackRequest:
      type: object
      properties:
        id:
          description: Unique id of the record for whom feedback is being provided.
          type: string
        feedback:
          description: Feedback on the AI response. It should be either "thumbsUp" or "thumbsDown".
          type: string
          enum:
            - thumbsDown
            - thumbsUp
        feedbackDetails:
          description: Optional qualitative feedback.
          type: string
      required:
        - id
        - feedback
    ArticlesUploadRequest:
      type: object
      properties:
        articles:
          type: array
          items:
            $ref: '#/components/schemas/Article'
      required:
        - articles
    ArticlesDeleteRequest:
      type: object
      properties:
        articles:
          type: array
          items:
            $ref: '#/components/schemas/DeleteArticle'
      required:
        - articles
    CasesUploadRequest:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Case'
      required:
        - data
    ResponseType:
      description: Indicates the type of response and how it was generated.
      type: string
      default: no-answer
      enum:
        - ai-answer-from-tickets
        - ai-answer-with-kb-links
        - ai-answer-from-incidents
        - generic
        - intent-flow
        - intent-tags
        - no-answer
      x-go-type-skip-optional-pointer: true
    AskRequest:
      type: object
      properties:
        productId:
          description: |
            If you have multiple products and knowledge base segmented by products, you can provide the product ID here.
          type: string
        author:
          description: |
            The author of the query, which can be used for personalization or tracking purposes.
          type: string
          enum:
            - agent
            - customer
        query:
          description: |
            The user's query or question to be processed by IrisGPT.
            It is the core input for generating a response.
          type: string
          x-oapi-codegen-extra-tags:
            validate: 'required,gte=1'
        voiceChannel:
          description: |
            Optional flag to indicate if the request is coming from a voice channel.
            When set to true, the response will not include source article links (links, linksTitle, and urls fields will be omitted).
            Defaults to false if not provided.
          type: boolean
          default: false
        images:
          description: |
            Optional screenshots attached to the query. Their text is OCR'd by a vision
            model and folded into the query before answering. At most 3 are accepted.
          type: array
          maxItems: 3
          items:
            $ref: '#/components/schemas/ChatScreenshotImage'
      required:
        - query
    ChatScreenshotImage:
      description: |
        A single screenshot attached to a chat query. Provide exactly one of url
        (https URL or data: URI) or base64 (raw base64 with mimeType).
      type: object
      properties:
        url:
          description: |
            Image URL (https) or a data URI. Mutually exclusive with base64.
          type: string
        base64:
          description: |
            Raw base64-encoded image bytes (no data URI prefix). Requires mimeType.
          type: string
        mimeType:
          description: |
            MIME type for base64 bytes, e.g. image/png.
          type: string
    AskResponseItem:
      description: |
        The `AskResponseItem` schema defines the structure of IrisGPT's response, including both the formatted and plain text versions of the answer, along with relevant links and URLs.
      type: object
      properties:
        responseType:
          $ref: '#/components/schemas/ResponseType'
        mdText:
          description: |
            The Markdown-formatted response from IrisGPT, including links and titles sourced from relevant articles.
          type: string
        intentTag:
          description: |
            The intent tag associated with the response, if applicable.
          type: string
          nullable: true
        procedure:
          description: |
            The name of the matched FAQ/procedure flow, if the response was generated by an FAQ match.
          type: string
          nullable: true
        escalate:
          description: |
            Whether this response is an escalation to a human agent, triggered by a FAQ procedure's [ESCALATE] marker.
          type: boolean
        htmltext:
          description: |
            The HTML-formatted response from IrisGPT, including links and titles sourced from relevant articles.
          type: string
        source:
          description: |
            The source of the response content, indicating where the information was obtained from.
          type: string
        plaintext:
          description: |
            A plain text version of IrisGPT's response, excluding any links.
          type: string
        linksTitle:
          description: |
            The title of the source articles, which can vary based on the request language.
          type: string
        links:
          description: |
            A list of objects containing URLs and their corresponding titles, representing articles referenced in the response.
          type: array
          items:
            $ref: '#/components/schemas/Link'
          nullable: true
          x-go-type-skip-optional-pointer: true
        urls:
          description: |
            A list of URLs corresponding to the source articles from which the response is derived.
          type: array
          items:
            type: string
          nullable: true
          x-go-type-skip-optional-pointer: true
        id:
          description: 'Unique identifier for the response, which can be used for tracking or reference.'
          type: string
      required:
        - htmltext
        - mdText
        - plaintext
        - source
        - id
    SentimentRequest:
      type: object
      properties:
        conversationId:
          description: Unique ticket or chat id
          type: string
          x-oapi-codegen-extra-tags:
            validate: 'required,gte=1'
        message:
          description: Support conversation that needs AI-powered sentiment analysis
          type: string
          x-oapi-codegen-extra-tags:
            validate: 'required,gte=1'
      required:
        - conversationId
        - message
    SentimentResponseItem:
      type: object
      properties:
        sentiment:
          description: AI-generated sentiment score ranging from -100 (very negative) to 100 (very positive)
          type: integer
          maximum: 100
          minimum: -100
          nullable: true
    Link:
      description: |
        The `Link` schema defines the structure for each link object included in IrisGPT's response.
        Each link consists of a title (or text) and its corresponding URL.
      type: object
      properties:
        text:
          description: |
            The title or descriptive text associated with the link.
          type: string
        url:
          description: |
            The URL of the source article or resource.
          type: string
          format: uri
      required:
        - text
        - url
    Comment:
      description: |
        Array of messages between the customer and the agent.
      type: object
      properties:
        comment:
          description: Message content
          type: string
          x-oapi-codegen-extra-tags:
            validate: 'required,gte=1'
        commenter:
          description: Author of the message
          type: string
          enum:
            - Customer
            - Agent
          x-oapi-codegen-extra-tags:
            validate: 'required,gte=1'
      required:
        - comment
        - commenter
    OutputFormat:
      type: string
      default: markdown
      enum:
        - markdown
        - html
      x-go-type-skip-optional-pointer: true
    SummaryRequest:
      type: object
      properties:
        conversationId:
          description: Unique ticket or chat id
          type: string
          x-oapi-codegen-extra-tags:
            validate: 'required,gte=1'
        subject:
          description: Initial query by the customer
          type: string
        description:
          description: Details on the initial query by the customer
          type: string
          x-go-type-skip-optional-pointer: true
        comments:
          description: Array of messages between customer and agent
          type: array
          items:
            $ref: '#/components/schemas/Comment'
          x-go-type-skip-optional-pointer: true
        format:
          $ref: '#/components/schemas/OutputFormat'
      required:
        - conversationId
    SummaryResponseItem:
      type: object
      properties:
        format:
          $ref: '#/components/schemas/OutputFormat'
        summary:
          description: Markdown-formatted summary of the conversation
          type: string
      required:
        - summary
        - format
    TagRequest:
      type: object
      properties:
        conversationId:
          description: Unique ticket or chat id
          type: string
          x-oapi-codegen-extra-tags:
            validate: 'omitempty,gte=1'
        message:
          description: Support conversation that needs to be auto-tagged
          type: string
          x-oapi-codegen-extra-tags:
            validate: 'omitempty,gte=1'
      oneOf:
        - required:
            - conversationId
        - required:
            - message
    TagResponseItem:
      type: object
      properties:
        tags:
          description: List of AI-generated tag components as key-value pairs
          type: array
          items:
            type: object
            additionalProperties:
              type: string
      required:
        - tags
    Error:
      type: object
      properties:
        error:
          description: Error message
          type: string
        code:
          description: HTTP status code for the error
          type: integer
        status:
          description: Status text corresponding to the error
          type: string
      required:
        - error
        - code
        - status
    Incident:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
        started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        shortlink:
          type: string
      required:
        - id
        - name
        - status
        - shortlink
        - started_at
        - updated_at
    IncidentComponents:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
        last_updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - status
        - last_updated_at
    AffectedComponent:
      type: object
      properties:
        name:
          type: string
        old_status:
          type: string
        new_status:
          type: string
      required:
        - name
        - old_status
        - new_status
    IncidentUpdate:
      type: object
      properties:
        impact:
          type: string
        status:
          type: string
        body:
          type: string
        created_at:
          type: string
          format: date-time
        affected_components:
          type: array
          items:
            $ref: '#/components/schemas/AffectedComponent'
      required:
        - impact
        - status
        - body
        - created_at
    IncidentPostmortem:
      type: object
    IncidentUploadRequest:
      type: object
      properties:
        incident:
          $ref: '#/components/schemas/Incident'
        components:
          items:
            $ref: '#/components/schemas/IncidentComponents'
          type: array
        updates:
          type: array
          items:
            $ref: '#/components/schemas/IncidentUpdate'
        postmortem:
          $ref: '#/components/schemas/IncidentPostmortem'
      required:
        - incident
        - components
        - updates
    SearchCase:
      type: object
      properties:
        id:
          description: Unique identifier for the case
          type: string
        subject:
          description: Subject of the case
          type: string
        url:
          description: Public link to the case
          type: string
          format: uri
        timeOfCreation:
          description: Unix timestamp epoch in milli-seconds as string
          type: integer
          format: int64
          example: 17437722600
        productId:
          description: 'Product ID associated with the case, if applicable'
          type: string
        score:
          description: 'Similarity score for the case, computed using Manhattan distance. A lower score indicates greater similarity.'
          type: number
          format: float
      required:
        - id
        - subject
        - url
        - timeOfCreation
    CasesSearchRequest:
      type: object
      properties:
        query:
          description: |
            The search query string. Optional if conversationId is provided.
          type: string
        conversationId:
          description: |
            Unique ticket or case ID to load the full ticket content (subject, description, and comments) for searching.
            Optional if query is provided. The ticket content will be loaded from the database and used as the search query.
            Note: The case with this conversationId will be excluded from the search results.
          type: string
        productId:
          description: |
            Product ID to filter cases. To filter across multiple products, pass a
            comma-separated list (e.g. "prod-a,prod-b"); results are searched per
            product and merged. Whitespace around commas is trimmed.
          type: string
        formId:
          description: The form ID to filter cases.
          type: string
        sourceBrandId:
          description: The source brand ID to filter cases.
          type: string
        filterUrls:
          description: |
            Array of case URLs to exclude from the search results. Cases with URLs matching any of these URLs will be filtered out.
          type: array
          items:
            type: string
            format: uri
        numResults:
          description: |
            (Legacy) Maximum number of results to return. Defaults to 4 if not specified.
            Prefer using offset and limit parameters for pagination.
          type: integer
          default: 4
          maximum: 100
          minimum: 1
        offset:
          description: |
            Number of results to skip for pagination. Used with limit parameter.
            If offset or limit is provided, pagination mode is used and numResults is ignored.
          type: integer
          format: uint
          default: 0
          minimum: 0
        limit:
          description: |
            Maximum number of results to return per page. Defaults to 25 in pagination mode.
            If offset or limit is provided, pagination mode is used and numResults is ignored.
            Note: offset + limit cannot exceed 200 due to external API constraints.
          type: integer
          format: uint
          default: 25
          maximum: 100
          minimum: 1
    CasesSearchResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchCase'
      required:
        - results
    SearchArticle:
      type: object
      properties:
        id:
          description: Unique identifier for the article
          type: string
        title:
          description: Title of the article
          type: string
        url:
          description: URL of the article
          type: string
          format: uri
        snippet:
          description: Brief snippet or excerpt from the article
          type: string
      required:
        - id
        - title
        - url
        - snippet
    ArticlesSearchResponse:
      type: object
      properties:
        articles:
          type: array
          items:
            $ref: '#/components/schemas/SearchArticle'
      required:
        - articles
  responses:
    '400':
      description: 'Bad Request - The server cannot process the request due to client error. This includes missing required fields, invalid data types, malformed JSON, or requests exceeding size limits.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized - Authentication is required and has failed or has not been provided. Your API key may be invalid or missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '408':
      description: Request Timeout - The server timed out waiting for the request to complete. The request may be retried.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '429':
      description: Too Many Requests - You have sent too many requests in a given amount of time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '504':
      description: 'Gateway Timeout - The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AskResponse:
      description: |
        The `AskResponse` represents the structure of the response returned by IrisGPT.
        It is formatted in JSON and contains the AI-generated answer to the user's query.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AskResponseItem'
    SentimentResponse:
      description: The AI-generated sentiment score for the conversation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SentimentResponseItem'
    SummaryResponse:
      description: The generated conversation summary
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SummaryResponseItem'
    TagResponse:
      description: The AI-generated tags for the conversation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TagResponseItem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        The `Authorization` header is required to authenticate API requests.
        It should contain a bearer token obtained through the IrisAgent portal.
security:
  - bearerAuth: []
