openapi: 3.1.0
info:
  title: Data Export
  version: 1.0.0
paths:
  /v2/export/conversations:
    get:
      operationId: get-conversations
      summary: Return conversations matching the parameters
      description: Returns a list of `conversation` objects along with a `next_page_uri` if applicable
      tags:
        - subpackage_conversations
      parameters:
        - name: created_since
          in: query
          description: >-
            Return records that were created after this date. If `created_to` is not specified, only records within 7
            days of this timestamp are returned. To retrieve data beyond that window, set `created_to` explicitly. Note
            that `updated_since` and `created_since` are mutually exclusive, so you must only use one in a request. Must
            be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API
            requests.
          required: false
          schema:
            type: string
            format: date-time
        - name: updated_since
          in: query
          description: >-
            Return records that were updated after this date. Note that `updated_since` and `created_since` are mutually
            exclusive, so you must only use one in a request. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g.,
            `2024-07-01T00:00:00Z`); required for valid API requests.
          required: false
          schema:
            type: string
            format: date-time
        - name: page_size
          in: query
          description: Number of records to return in response. The maximum and default is 10000, the minimum is 100.
          required: false
          schema:
            type: integer
            default: 10000
        - name: created_to
          in: query
          description: >-
            Return records that were created earlier than this date. If `created_since` is used and this parameter is
            not specified, this value defaults to 7 days after `created_since`. Must be an ISO 8601 UTC timestamp ending
            with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
          required: false
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: updated_to
          in: query
          description: >-
            Return records that were updated earlier than this date. If `updated_since` is used and this parameter is
            not specified, this value defaults to 7 days after `updated_since`. Must be an ISO 8601 UTC timestamp ending
            with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API requests.
          required: false
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ada successfully processed the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationsResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/export/messages:
    get:
      operationId: get-messages
      summary: Return messages matching the parameters
      description: Returns a list of `message` objects along with a `next_page_uri` if applicable
      tags:
        - subpackage_messages
      parameters:
        - name: created_since
          in: query
          description: >-
            Return records that were created after this date. If `created_to` is not specified, only records within 7
            days of this timestamp are returned. To retrieve data beyond that window, set `created_to` explicitly. Must
            be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`); required for valid API
            requests.
          required: true
          schema:
            type: string
            format: date-time
        - name: conversation_id
          in: query
          description: Return records with a `conversation_id` that matches this id
          required: false
          schema:
            type:
              - string
              - 'null'
            format: id
        - name: page_size
          in: query
          description: Number of records to return in response. The maximum and default is 10000, the minimum is 100.
          required: false
          schema:
            type: integer
            default: 10000
        - name: created_to
          in: query
          description: >-
            Return records that were created earlier than this date. If not specified, this value defaults to 7 days
            after `created_since`. Must be an ISO 8601 UTC timestamp ending with 'Z' (e.g., `2024-07-01T00:00:00Z`);
            required for valid API requests.
          required: false
          schema:
            type:
              - string
              - 'null'
            format: date-time
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ada successfully processed the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessagesResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
servers:
  - url: https://example.ada.support/api
components:
  schemas:
    ConversationCsat:
      type: object
      properties: {}
      description: Object of customer satisfaction survey data for this conversation
      title: ConversationCsat
    ConversationMetavariables:
      type: object
      properties: {}
      description: Object of metavariables and their values active during this conversations
      title: ConversationMetavariables
    ConversationVariables:
      type: object
      properties: {}
      description: Object of autocapture and global variables and their values last active during this conversations
      title: ConversationVariables
    Conversation:
      type: object
      properties:
        _id:
          type: string
          description: Unique ID for the conversation record
        agent_id:
          type: array
          items:
            type: string
          description: The list of unique IDs for agents involved in the conversation
        agent_handle_time:
          type: number
          format: double
          description: Time taken for a human agent to handle a conversation in seconds
        agent_name:
          type: array
          items:
            type: string
          description: A list of names of the agents involved the conversation, corresponding to the agent IDs
        automated_resolution_classification:
          type: string
          description: Classification of either Resolved or Not Resolved for the conversation
        automated_resolution_classification_reason:
          type: string
          description: Explanation of the reason for the assigned automated_resolution_classification
        bot_handle_time:
          type: number
          format: double
          description: Time taken for the AI agent to handle a conversation in seconds
        browser:
          type: string
          description: The browser used by the chatter
        browser_version:
          type: string
          description: The version of the browser used by the chatter
        chatter_id:
          type: string
          description: Ada ID of the chatter having this conversation
        csat:
          $ref: '#/components/schemas/ConversationCsat'
          description: Object of customer satisfaction survey data for this conversation
        date_created:
          type: string
          format: date-time
          description: Date and time the record was created (UTC)
        date_updated:
          type: string
          format: date-time
          description: Last date and time the record was updated (UTC)
        device:
          type: string
          description: The device the chatter used, such as iphone, android, etc.
        end_user_id:
          type:
            - string
            - 'null'
          description: The End User ID used to identify the chatter profile in the conversation
        generated_topic_id:
          type: string
          description: The unique ID Ada associated with the generated conversation topic
        generated_topic_label:
          type:
            - string
            - 'null'
          description: The title of the generated conversation topic
        generated_topic_v2_id:
          type:
            - string
            - 'null'
          description: The unique ID Ada associated with the generated conversation topic using Topics V2
        generated_topic_v2_title:
          type:
            - string
            - 'null'
          description: The title of the generated conversation topic using Topics V2
        generated_topic_v2_desc:
          type:
            - string
            - 'null'
          description: The descrtiption of the generated conversation topic using Topics V2
        generated_topic_v2_parent_id:
          type:
            - string
            - 'null'
          description: >-
            The unique ID Ada associated with the generated conversation topic's parent category topic. Null if topic
            has no parent category topic.
        inquiry_summary:
          type: string
          description: An automatically generated summary of the customer's inquiry
        is_engaged:
          type: boolean
          description: Whether the chatter engaged with the bot during this conversation
        is_escalated:
          type: boolean
          description: Whether the chatter escalated to a live agent during this conversation
        is_test_user:
          type: boolean
          description: Whether the conversation was started by a test user
        language:
          type: string
          description: The language the chatter used
        metavariables:
          $ref: '#/components/schemas/ConversationMetavariables'
          description: Object of metavariables and their values active during this conversations
        oauth_channel:
          type: string
          description: The channel used by Oauth
        platform:
          type: string
          description: Ada platform through which this conversation occurred
        record_last_updated:
          type:
            - string
            - 'null'
          format: date-time
          description: Date and time the record was uploaded to the API
        variables:
          $ref: '#/components/schemas/ConversationVariables'
          description: Object of autocapture and global variables and their values last active during this conversations
      title: Conversation
    ConversationsResponseMeta:
      type: object
      properties:
        next_page_uri:
          type:
            - string
            - 'null'
          description: Link to the next page of results matching the query
      title: ConversationsResponseMeta
    ConversationsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
          description: Records returned from the query
        meta:
          $ref: '#/components/schemas/ConversationsResponseMeta'
      title: ConversationsResponse
    ErrorsErrorsItems:
      type: object
      properties:
        type:
          type: string
          description: The error type
        message:
          type: string
          description: The error message
        details:
          type:
            - string
            - 'null'
          description: Extra information about the error
      required:
        - type
        - message
      title: ErrorsErrorsItems
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorsErrorsItems'
          description: A list of errors
      required:
        - errors
      title: Errors
    MessageMessageData:
      type: object
      properties: {}
      description: Data associated with this message
      title: MessageMessageData
    Message:
      type: object
      properties:
        _id:
          type: string
          description: Unique ID for the message record
        answer_id:
          type:
            - string
            - 'null'
          description: >-
            Internal ID of the answer (response) that triggered this message. Null if the message was not sent by an Ada
            bot, and None if it was sent by a generative bot.
        answer_title:
          type:
            - string
            - 'null'
          description: >-
            Title of the answer (response) that triggered this message. Null if the message was not sent by an Ada bot,
            or if it was sent by a generative bot.
        chatter_id:
          type:
            - string
            - 'null'
          description: Internal ID of the chatter who sent this message. Corresponds to the `_id` field of Chatter objects.
        conversation_id:
          type: string
          description: >-
            Internal ID of the conversation in which this message was sent. Corresponds to the `_id` field of
            Conversation objects.
        date_created:
          type: string
          format: date-time
          description: Time the record was created (UTC)
        link_was_clicked:
          type:
            - boolean
            - 'null'
          description: Indicates if the link in the answer (response) was clicked
        message_data:
          $ref: '#/components/schemas/MessageMessageData'
          description: Data associated with this message
        recipient:
          type: string
          description: Recipient of this message
        record_last_updated:
          type: string
          format: date-time
          description: Date and time the record was uploaded to the API (UTC)
        review:
          type: integer
          description: Rating given to this answer by the chatter
        sender:
          type: string
          description: Sender of this message
        in_response_to:
          type: string
          description: >-
            Internal ID of the message that this message is in response to. None if the message is not in response to
            another message.
      title: Message
    MessagesResponseMeta:
      type: object
      properties:
        next_page_uri:
          type:
            - string
            - 'null'
          description: Link to the next page of results matching the query
      title: MessagesResponseMeta
    MessagesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: Records returned from the query
        meta:
          $ref: '#/components/schemas/MessagesResponseMeta'
      title: MessagesResponse
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
