Emporix Conversation API

openapi: 3.2.0
info:
  title: Emporix Conversation API
  version: ''
  contact:
    name: Emporix
    url: https://emporix.com
    email: documentation@emporix.com
  description: 'Operations tagged Conversation across 2 of this provider''s published API definitions: emporix-ai-service-openapi.yml, emporix-ai-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
tags:
- name: Conversation
  description: Manage Agent Conversations
paths:
  /ai-service/{tenant}/agentic/conversations:
    parameters:
    - $ref: '#/components/parameters/path_tenant'
    - $ref: '#/components/parameters/qParam'
    - $ref: '#/components/parameters/pageSize'
    - $ref: '#/components/parameters/pageNumber'
    - $ref: '#/components/parameters/sort'
    - $ref: '#/components/parameters/fields'
    - $ref: '#/components/parameters/header_xTotalCount'
    get:
      summary: Listing conversations
      operationId: GET-ai-list-conversations
      responses:
        '200':
          description: List of conversations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationResponse'
              examples:
                Conversations Response:
                  $ref: '#/components/examples/ConversationsResponse'
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
      description: Retrieves agent conversations based on the provided query.
      security:
      - OAuth2:
        - ai.agent_read
      tags:
      - Conversation
    servers:
    - url: https://api.emporix.io
  /ai-service/{tenant}/agentic/conversations/search:
    parameters:
    - $ref: '#/components/parameters/path_tenant'
    post:
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageNumber'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/header_xTotalCount'
      summary: Searching conversations
      operationId: POST-ai-search-conversations
      responses:
        '200':
          description: List of conversations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationResponse'
              examples:
                Conversations Response:
                  $ref: '#/components/examples/ConversationsResponse'
        '400':
          $ref: '#/components/responses/400_resp_common'
        '401':
          $ref: '#/components/responses/401_resp_common'
        '403':
          $ref: '#/components/responses/403_resp_common'
      requestBody:
        $ref: '#/components/requestBodies/QParamSearchBody'
      description: Searches for agent conversations based on the provided query.
      security:
      - OAuth2:
        - ai.agent_read
      tags:
      - Conversation
    servers:
    - url: https://api.emporix.io
components:
  responses:
    400_resp_common:
      description: The request was syntactically incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Code must not be null:
              value:
                code: 400
                status: Bad Request
                message: Validation problem with request body.
                details:
                - message: code must not be null nor blank
    403_resp_common:
      description: Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Access forbidden:
              value:
                code: 403
                status: Forbidden
                message: The access to the requested resource has been forbidden by the server.
    401_resp_common:
      description: The authorization token is invalid or has expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageFault'
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            Access token expired:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
  schemas:
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
        type:
          type: string
        message:
          type: string
        moreInfo:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              type:
                type: string
              message:
                type: string
              moreInfo:
                type: string
      description: ''
    QParamSearchBody:
      type: object
      properties:
        q:
          type: string
          description: "A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"
    ErrorMessageFault:
      type: object
      properties:
        fault:
          type: object
          properties:
            faultstring:
              type: string
            detail:
              type: object
              properties:
                errorcode:
                  type: string
    ConversationResponse:
      type: object
      description: Represents an active agent conversation context (MS Teams channel or group chat).
      properties:
        conversationId:
          type: string
          description: Provider-side conversation identifier (Teams conversation ID).
        conversationName:
          type: string
          description: Human-readable name of the conversation channel or group chat.
        contextRef:
          type: string
          description: Caller-supplied reference key used to reuse an existing conversation.
        channelId:
          type: string
          description: Teams channel or chat identifier.
        agentId:
          type: string
          description: Identifier of the agent that owns this conversation.
        sessionId:
          type: string
          description: LangGraph session (checkpointer) ID for agent continuity.
        lastMessageAt:
          type: string
          format: date-time
          description: Timestamp of the last message activity in this conversation.
  parameters:
    qParam:
      in: query
      name: q
      description: 'A standard query parameter is used to search for specific values.


        See: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)

        '
      schema:
        type: string
    header_xTotalCount:
      schema:
        type: boolean
      in: header
      name: X-Total-Count
      description: Flag indicating whether the total number of retrieved results should be returned.
    path_tenant:
      name: tenant
      in: path
      required: true
      schema:
        type: string
      description: 'Your Emporix tenant name.


        **Note**: The tenant name should always be provided in lowercase.

        '
    pageNumber:
      schema:
        type: string
      in: query
      name: pageNumber
      description: The page number to be retrieved. The size of the pages should be specified by the `pageSize` parameter.
    pageSize:
      schema:
        type: string
      in: query
      name: pageSize
      description: The number of documents to be retrieved per page.
    sort:
      schema:
        type: string
      in: query
      name: sort
      description: List of properties used to sort the results, separated by colons.
    fields:
      schema:
        type: string
      in: query
      name: fields
      description: Fields to be returned in the response.
  requestBodies:
    QParamSearchBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QParamSearchBody'
          examples:
            Search Request:
              value:
                q: name:~Complaint
  examples:
    ConversationsResponse:
      value:
      - conversationId: 19:abc123@thread.tacv2
        conversationName: 'Support - Order #12345'
        contextRef: order-12345
        channelId: 19:abc123@thread.tacv2
        agentId: generic-agent-id
        sessionId: session-abc
        lastMessageAt: '2026-07-10T08:00:00Z'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            ai.text_manage: Needed to execute actions related to the text generation.
            ai.completion_manage: Needed to execute actions related to the AI completions.
            ai.agentexecution_manage: Needed to execute agentic chat.
            ai.agentexecution_manage_own: Needed to execute agentic chat by customers.
            ai.agent_read: Needed to read AI agents.
            ai.agent_manage: Needed to manage AI agents.
          tokenUrl: https://api.emporix.io/oauth/token
x-refined-from:
- emporix-ai-service-openapi.yml
- emporix-ai-service-openapi.yml