openapi: 3.1.0
info:
  title: Ada API V2
  description: Ada API V2
  version: 2.0.0
  contact:
    name: Ada Support
    email: help@ada.support
tags:
- name: Channels
  description: Manage Channels
- name: Conversations
  description: Manage Conversations
- name: End Users
  description: Manage End Users
- name: Knowledge
  description: Manage Knowledge Content
- name: Conversation Webhooks
  description: Webhooks for conversation-related events
- name: End User Webhooks
  description: Webhooks for end user-related events
- name: Platform Integrations
  description: Manage Platform Integrations
- name: Webhook Management
  description: Manage webhook endpoint subscriptions and signing secrets

paths:
  /v2/end-users/{end_user_id}:
    get:
      operationId: getEndUserById
      summary: Get an end user
      description: Get a specific end user by id
      security:
      - BearerAuth: []
      tags:
      - End Users
      parameters:
      - in: path
        name: end_user_id
        description: The Ada end_user_id
        schema:
          type: string
          format: id
          examples:
          - 5df263b7db5a7e6ea03fae9b
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    patch:
      operationId: patchEndUserById
      summary: Update an end user
      description: Update a specific end user by id
      security:
      - BearerAuth: []
      tags:
      - End Users
      parameters:
      - in: path
        name: end_user_id
        description: The Ada end_user_id
        schema:
          type: string
          format: id
          examples:
          - 5df263b7db5a7e6ea03fae9b
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '409':
          description: >-
            Conflict — the requested external_id is already assigned to a
            different end user on this AI Agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                DuplicateResourceError:
                  $ref: '#/components/examples/DuplicateResourceError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/end-users/:
    get:
      operationId: getEndUsers
      summary: Get multiple end users
      description: >-
        Get multiple end users. You can specify how many users appear per page,
        and which user id to start from. Alternatively, supply an `external_id`
        query parameter to look up a single end user by their caller-supplied
        identifier. When `external_id` is supplied, the 200 response is a
        single end user object (same shape as `GET /v2/end-users/{end_user_id}`)
        and is mutually exclusive with cursor/limit pagination. The `external_id`
        query parameter is available for custom channel integrations only (V1).
      security:
      - BearerAuth: []
      tags:
      - End Users
      parameters:
      - in: query
        name: external_id
        description: >-
          Look up a single end user by the external identifier set at creation
          or via PATCH. Returns the matching end user with the same shape as
          GET /v2/end-users/{end_user_id}, or 404 if no mapping exists.
          Mutually exclusive with cursor/limit pagination. Available for custom
          channel integrations only (V1).
        schema:
          type: string
          maxLength: 36
          examples:
          - user-12345
        required: false
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: >-
            OK. When `external_id` is supplied, returns a single end user
            object. Otherwise returns a paginated list of end users.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/EndUser'
                - $ref: '#/components/schemas/EndUsers'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found — no end user is mapped to the requested external_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    post:
      operationId: createEndUser
      summary: Create an end user
      description: >-
        Create a new end user with optional profile data and sensitive metadata.
        Use this endpoint to establish an end user with context (language, metadata,
        sensitive metadata) before starting a conversation via POST /v2/conversations/.
        This ensures the AI Agent has full user context from the first turn.
        Available for custom channel (Conversations API) integrations.
        End users created through this endpoint that are not associated with
        a conversation within 24 hours of creation are automatically deleted.
      security:
      - BearerAuth: []
      tags:
      - End Users
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEndUserRequest'
      responses:
        '200':
          description: >-
            Existing end user returned. Issued when the request includes an
            external_id that is already mapped to an end user on the same AI
            Agent (idempotent upsert).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '413':
          description: Content Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ContentTooLargeError:
                  $ref: '#/components/examples/ContentTooLargeError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/knowledge/sources/:
    get:
      description: Get knowledge sources
      summary: Get knowledge sources
      operationId: getManyKnowledgeSources
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      responses:
        '200':
          description: Knowledge sources
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeSourceResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    post:
      description: Create a knowledge source
      summary: Create a knowledge source
      operationId: createSingleKnowledgeSource
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeSourceCreateRequest'
      responses:
        '200':
          description: Knowledge source created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeSourceResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '409':
          description: Duplicate Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                DuplicateResourceError:
                  $ref: '#/components/examples/DuplicateResourceError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/knowledge/sources/{id}:
    patch:
      description: Update a knowledge source
      summary: Update a knowledge source
      operationId: updateSingleKnowledgeSource
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      parameters:
      - in: path
        name: id
        description: id of the knowledge source to update
        schema:
          type: string
          examples:
          - 5df263b7db5a7e6ea03fae9b
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeSourceUpdateRequest'
      responses:
        '200':
          description: Knowledge source updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeSourceResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    delete:
      description: Delete a knowledge source, and its related articles
      summary: Delete a knowledge source
      operationId: deleteSingleKnowledgeSource
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      parameters:
      - in: path
        name: id
        description: id of the knowledge source to delete
        schema:
          type: string
          examples:
          - 5df263b7db5a7e6ea03fae9b
        required: true
      responses:
        '204':
          description: Knowledge source deleted
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/knowledge/articles/:
    get:
      description: Get knowledge articles
      summary: Get knowledge articles
      operationId: getManyArticles
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      parameters:
      - in: query
        name: cursor
        description: The article cursor that marks the start or beginning of the returned
          article records
        schema:
          type: string
          format: id
          examples:
          - 5df263b7db5a7e6ea03fae9b
        required: false
      - in: query
        name: limit
        description: The number of article records to return
        schema:
          type: integer
          minimum: 1
          maximum: 100
          examples:
          - 10
        required: false
      - in: query
        name: id
        description: Filter by article id
        schema:
          type: array
          items:
            type: string
            format: id
          examples:
          - - 5df263b7db5a7e6ea03fae9b
            - 5df263b7db5a7e6ea03fae9c
      - in: query
        name: enabled
        description: Filter by enabled status
        schema:
          type: array
          items:
            type: boolean
          examples:
          - true
      - in: query
        name: language
        description: Filter by language
        schema:
          type: array
          items:
            type: string
          examples:
          - - en
            - fr
      - in: query
        name: knowledge_source_id
        description: Filter by knowledge source
        schema:
          type: array
          items:
            type: string
            format: id
          examples:
          - - 5df263b7db5a7e6ea03fae9b
            - 5df263b7db5a7e6ea03fae9c
      - in: query
        name: tag_ids
        description: Filter by tag ids
        schema:
          type: array
          items:
            type: string
            format: id
          examples:
          - - 5df263b7db5a7e6ea03fae9b
            - 5df263b7db5a7e6ea03fae9c
      responses:
        '200':
          description: Matching knowledge articles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeArticleResponse'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadata'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    delete:
      description: Delete multiple articles
      summary: Delete multiple articles
      operationId: deleteManyArticles
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      parameters:
      - in: query
        name: id
        description: Filter by article id
        schema:
          type: array
          items:
            type: string
            format: id
          examples:
          - - 5df263b7db5a7e6ea03fae9b
            - 5df263b7db5a7e6ea03fae9c
      - in: query
        name: enabled
        description: Filter by enabled status
        schema:
          type: array
          items:
            type: boolean
          examples:
          - - true
            - false
      - in: query
        name: language
        description: Filter by language
        schema:
          type: array
          items:
            type: string
          examples:
          - - en
            - fr
      - in: query
        name: knowledge_source_id
        description: Filter by knowledge source
        schema:
          type: array
          items:
            type: string
            format: id
          examples:
          - - 5df263b7db5a7e6ea03fae9b
            - 5df263b7db5a7e6ea03fae9c
      - in: query
        name: tag_ids
        description: Filter by tag ids
        schema:
          type: array
          items:
            type: string
            format: id
          examples:
          - - 5df263b7db5a7e6ea03fae9b
            - 5df263b7db5a7e6ea03fae9c
      responses:
        '204':
          description: Articles successfully deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/knowledge/articles/{id}:
    get:
      description: Get knowledge article by id
      summary: Get a single knowledge article
      operationId: getSingleArticle
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      parameters:
      - in: path
        name: id
        description: The id of the article to retrieve
        schema:
          type: string
          examples:
          - 5df263b7db5a7e6ea03fae9b
        required: true
      responses:
        '200':
          description: Knowledge article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeArticleResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    delete:
      description: Delete an article
      summary: Delete a single article
      operationId: deleteSingleArticle
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      parameters:
      - in: path
        name: id
        description: The id of the article to delete
        schema:
          type: string
          examples:
          - 5df263b7db5a7e6ea03fae9b
        required: true
      responses:
        '204':
          description: Articles successfully deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/knowledge/tags/:
    get:
      description: Get article tags
      summary: Get article tags
      operationId: getManyTags
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      responses:
        '200':
          description: Article tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArticleTag'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/knowledge/tags/{id}:
    delete:
      description: Delete an article tag
      summary: Delete a single article tag
      operationId: deleteSingleTag
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      parameters:
      - in: path
        name: id
        description: The id of the article tag to delete
        schema:
          type: string
          examples:
          - 5df263b7db5a7e6ea03fae9b
        required: true
      responses:
        '204':
          description: Article tag deleted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/knowledge/bulk/articles/:
    post:
      description: 'Upsert an array of knowledge articles


        This endpoint will create or update articles based on the unique `id` field
        of each article. If an article with the same `id` already exists, it will
        be updated. Otherwise, a new article will be created.


        **Limits:**

        - The maximum size of a request payload is 10MB

        - The maximum size of an article is 100KB

        - The maximum number of articles is 50,000

        '
      summary: Upsert multiple articles
      operationId: upsertManyArticles
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/KnowledgeArticleUpsertRequest'
              minItems: 1
      responses:
        '200':
          description: Articles upserted
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeArticleUpsertResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/knowledge/bulk/tags/:
    post:
      description: 'Upsert an array of tags for articles


        This endpoint will create or update tags based on the unique `id` field of
        each tag. If a tag with the same `id` already exists, it will be updated.
        Otherwise, a new tag will be created.

        '
      summary: Upsert multiple tags
      operationId: upsertManyTags
      security:
      - BearerAuth: []
      tags:
      - Knowledge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              description: A list of tags
              items:
                $ref: '#/components/schemas/ArticleTag'
              minItems: 1
      responses:
        '200':
          description: Tags upserted
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArticleTagUpsertResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/platform-integrations/:
    get:
      description: Get a list of platform integrations owned by your account (e.g. a developer sandbox)
      summary: List integrations
      operationId: getPlatformIntegrations
      security:
        - BearerAuth: [ ]
      tags:
        - Platform Integrations
      parameters:
        - $ref: '#/components/parameters/CursorParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Platform integrations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlatformIntegration'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadata'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                DuplicateResourceError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    post:
      security:
        - BearerAuth: [ ]
      description: 'Create an integration. Integrations are created in `development` status by default.'
      summary: Create an integration
      operationId: createPlatformIntegration
      tags:
        - Platform Integrations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformIntegrationCreateRequest'
      responses:
        '200':
          description: Platform integration created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PlatformIntegration'
                  - type: object
                    properties:
                      client_secret:
                        type: string
                        description: The OAuth client secret for the integration
                        examples:
                          - "a4a908jgf9a8gh9a"
                        readOnly: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/AuthorizationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/platform-integrations/{id}:
    patch:
      summary: Update an integration
      description: 'Update a platform integration. **_Note:_ only integrations in development may be updated. Integrations submitted for publication cannot be updated.**'
      operationId: updateSinglePlatformIntegration
      security:
        - BearerAuth: [ ]
      tags:
        - Platform Integrations
      parameters:
        - in: path
          name: id
          description: The ID of the platform integration to update
          schema:
            type: string
            format: id
            examples:
              - "5df263b7db5a7e6ea03fae9b"
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformIntegrationUpdateRequest'
      responses:
        '200':
          description: Platform integration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformIntegration'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/AuthorizationError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/platform-integrations/{id}/installations/self:
    get:
      description: Get the platform integration installation associated with the
        access token. Use this endpoint to get the details of an installation, including the configuration form completed by the admin.
      summary: Get an installation
      operationId: getPlatformIntegrationInstallationSelf
      security:
        - BearerAuth: [ ]
      tags:
        - Platform Integrations
      parameters:
        - in: path
          name: id
          description: The ID of the platform integration to fetch installation for
          schema:
            type: string
            format: id
            examples:
              - "5df263b7db5a7e6ea03fae9b"
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformIntegrationInstallation'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/AuthorizationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/platform-integrations/{platform_integration_id}/installations/{installation_id}:
    patch:
      description: Update status after installation. An installation can be `complete` or `incomplete`.
      summary: Update installation status
      operationId: updatePlatformIntegrationInstallation
      security:
        - BearerAuth: [ ]
      tags:
        - Platform Integrations
      parameters:
        - in: path
          name: platform_integration_id
          description: The ID of the platform integration
          schema:
            type: string
            format: id
            examples:
              - "5df263b7db5a7e6ea03fae9b"
          required: true
        - in: path
          name: installation_id
          description: The ID of the installation to update
          schema:
            type: string
            format: id
            examples:
              - "5df263b7db5a7e6ea03fae9b"
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformIntegrationInstallationUpdateRequest'
      responses:
        '200':
          description: Installation updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformIntegrationInstallation'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/AuthorizationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /v2/conversations/email/:
    post:
      operationId: createEmailConversation
      tags:
      - Conversations
      summary: Start a conversation over Ada's email channel
      description: Start a conversation with an end user over Ada's native Email channel, providing context for their inquiry. **This endpoint is exclusive to the native Email channel and cannot be used for custom channels.** Your AI Agent can start conversations only with the default Ada-provided email address, or with email addresses you’ve configured through Bring Your Own Domain (BYOD) settings.
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailConversationCreateRequest'
      responses:
        '200':
          description: Conversation Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailConversationCreateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnprocessableEntityError:
                  $ref: '#/components/examples/UnprocessableContentError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

  /v2/channels/:
    post:
      operationId: createChannel
      summary: Create a new channel
      description: Create a new channel. A maximum of 100 channels can be created per account per day. The maximum request size is 10MB.
      security:
        - BearerAuth: [ ]
      tags:
        - Channels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomChannel'
      responses:
        '201':
          description: Channel created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomChannel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '413':
          description: Content Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                RequestEntityTooLargeError:
                  $ref: '#/components/examples/ContentTooLargeError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

    get:
      description: Get a list of channels. This list can be filtered by modality and paginated. The default and maximum limits are 100 channels per page
      operationId: getChannels
      summary: Get a list of channels
      security:
        - BearerAuth: [ ]
      tags:
        - Channels
      parameters:
        - $ref: '#/components/parameters/LimitParam'
        - in: query
          name: cursor
          description: >-
            The ID that marks the start or beginning of the returned records
          schema:
            # NOTE: Typically cursors should expect `format: id`, but here we need to allow b64 encoded strings
            # which are used for the IDs of native channel
            type: string
            examples:
              - '5f7e0e2c1e7c7e000f0f9c3a'
          required: false
        - in: query
          name: type
          description: The type of the channels to retrieve
          schema:
            type: string
            enum:
              - custom
              - native
            examples:
              - custom
              - native
          required: true
        - in: query
          name: modality
          description: The modality of the channels to retrieve
          schema:
            type: string
            enum:
              - messaging
              - email
              - voice
            examples:
              - messaging
              - email
              - voice
          required: false
      responses:
        '200':
          description: Channels
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
                  meta:
                    $ref: '#/components/schemas/PaginationMetadata'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

  /v2/conversations/:
    post:
      operationId: createConversation
      tags:
        - Conversations
      summary: Create a new conversation
      description: >-
        Create a new conversation. If `end_user_id` is not provided, the system creates a new end user automatically.
        The maximum request size is 10MB, and metadata must not exceed 4KB.
      security:
        - BearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
      responses:
        '201':
          description: Conversation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

  /v2/conversations/{conversation_id}/:
    get:
      operationId: getConversationById
      summary: Get a conversation
      description: Get a conversation by its ID
      security:
        - BearerAuth: [ ]
      tags:
        - Conversations
      parameters:
        - in: path
          name: conversation_id
          schema:
            type: string
            format: id
            examples:
              - 5df263b7db5a7e6ea03fae9b
          required: true
          description: The ID of the conversation to retrieve
      responses:
        '200':
          description: Conversation retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    patch:
      operationId: patchConversationById
      summary: Update a conversation
      description: Update a conversation's metadata by its ID
      security:
        - BearerAuth: [ ]
      tags:
        - Conversations
      parameters:
        - in: path
          name: conversation_id
          schema:
            type: string
            format: id
            examples:
              - 5df263b7db5a7e6ea03fae9b
          required: true
          description: The ID of the conversation to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationPatchRequest'
      responses:
        '200':
          description: Conversation updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

  /v2/conversations/{conversation_id}/messages/:
    post:
      operationId: createMessage
      summary: Create a new message
      description: Create a new message in a conversation. The maximum request size is 10MB.
      security:
        - BearerAuth: [ ]
      tags:
        - Conversations
      parameters:
        - in: path
          name: conversation_id
          schema:
            type: string
            format: id
            examples:
              - 5df263b7db5a7e6ea03fae9b
          required: true
          description: The ID of the conversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreateRequest'
      responses:
        '201':
          description: Message created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
    get:
      operationId: fetchConversationMessagesById
      summary: Get conversation messages
      description: Get messages (paginated) for a conversation by its ID
      security:
        - BearerAuth: [ ]
      tags:
        - Conversations
      parameters:
        - in: path
          name: conversation_id
          schema:
            type: string
            format: id
            examples:
              - 5df263b7db5a7e6ea03fae9b
          required: true
          description: The ID of the conversation
        - in: query
          name: cursor
          schema:
            type: string
            examples:
              - MjAyMC0wOS0yMFQwMDowMDowMSswMDowMA==
          required: false
          description: Cursor for pagination. Use the value from `meta.next_page_url` in the previous response.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            examples:
              - 100
          required: false
          description: Maximum number of messages to return (default 100, max 100)
      responses:
        '200':
          description: List of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

  /v2/conversations/{conversation_id}/end/:
    post:
      operationId: endConversation
      summary: End a conversation
      description: Ends the conversation specified by the `conversation_id`
      security:
        - BearerAuth: [ ]
      tags:
        - Conversations
      parameters:
        - in: path
          name: conversation_id
          description: The ID of the conversation to end
          required: true
          schema:
            type: string
            format: id
            examples:
              - 5df263b7db5a7e6ea03fae9b
      responses:
        '200':
          description: Conversation ended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - "Conversation ended successfully."
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

  /v2/conversations/{conversation_id}/end-handoff/:
    post:
      operationId: endHandoff
      description: Ends the handoff for the conversation specified by the `conversation_id`. This endpoint returns control to the AI Agent and does not end the conversation. It also triggers CSAT for human agent (where applicable), leftover blocks processing, and agent presence dismissal messages.
      security:
        - BearerAuth: [ ]
      tags:
        - Conversations
      parameters:
        - in: path
          name: conversation_id
          description: The ID of the conversation to end handoff for
          required: true
          schema:
            type: string
            format: id
            examples:
              - 5df263b7db5a7e6ea03fae9b
      responses:
        '200':
          description: Handoff ended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - "Handoff ended successfully."
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '422':
          description: Conversation is not in an active handoff state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnprocessableContentError:
                  $ref: '#/components/examples/UnprocessableContentError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

  /v2/conversations/{conversation_id}/attachments/:
    post:
      operationId: uploadAttachment
      summary: Upload a file attachment
      description: |
        Upload a file attachment to a conversation. The file will be stored and a presigned URL
        will be generated that is valid for 7 days. The maximum file size is 50MB.

        The presigned URL can be used to create a file message by calling the
        `/v2/conversations/{conversation_id}/messages/` endpoint with `content.type` set to `file`.

        **Note:** Attachments can only be uploaded when the conversation is in a handoff state.

        **Allowed file types:** TXT, LOG, CSV, EML, PNG, SVG, JPEG, JPG, GIF, HEIF, HEIC, AVIF, WAV, M4A, MP3, MP4, M4V, MOV, MPEG, MPG, ZIP, PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, Keynote, Pages, Numbers
      security:
        - BearerAuth: [ ]
      tags:
        - Conversations
      parameters:
        - in: path
          name: conversation_id
          description: The ID of the conversation
          required: true
          schema:
            type: string
            format: id
            examples:
              - 5df263b7db5a7e6ea03fae9b
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload (max 50MB)
              required:
                - file
      responses:
        '201':
          description: Attachment uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentUploadResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                BadRequestError:
                  $ref: '#/components/examples/BadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                UnauthorizedError:
                  $ref: '#/components/examples/UnauthorizedError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                NotFoundError:
                  $ref: '#/components/examples/NotFoundError'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'

  /v2/webhooks/:
    get:
      operationId: listWebhooks
      summary: List webhooks
      description: List all webhook subscriptions configured for this AI Agent
      security:
        - BearerAuth: []
      tags:
        - Webhook Management
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of webhooks to return
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Cursor for pagination
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
                  meta:
                    type: object
                    properties:
                      next_page_url:
                        description: URL for the next page of results, or null if no pages remain
                        type:
                          - string
                          - 'null'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: createWebhook
      summary: Create a webhook
      description: Create a new webhook subscription. If this is the first webhook for this AI Agent, the webhook infrastructure is automatically provisioned
      security:
        - BearerAuth: []
      tags:
        - Webhook Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  description: The URL that will receive webhook events
                  type: string
                  format: uri
                  examples:
                    - https://example.com/webhooks
                description:
                  description: A description of the webhook
                  type: string
                  default: ''
                event_filters:
                  description: Event types to subscribe to. An empty list subscribes to all events
                  type: array
                  items:
                    type: string
                  default: []
                  examples:
                    - - v1.conversation.created
                      - v1.conversation.ended
                enabled:
                  description: Whether the webhook is enabled
                  type: boolean
                  default: true
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'

  /v2/webhooks/{id}:
    get:
      operationId: getWebhook
      summary: Get a webhook
      description: Get the details of a specific webhook subscription
      security:
        - BearerAuth: []
      tags:
        - Webhook Management
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The webhook ID
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      operationId: updateWebhook
      summary: Update a webhook
      description: Update a webhook subscription. Only the fields provided in the request body will be updated
      security:
        - BearerAuth: []
      tags:
        - Webhook Management
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The webhook ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  description: The URL that will receive webhook events
                  type: string
                  format: uri
                description:
                  description: A description of the webhook
                  type: string
                event_filters:
                  description: Event types to subscribe to. An empty list subscribes to all events
                  type: array
                  items:
                    type: string
                enabled:
                  description: Whether the webhook is enabled
                  type: boolean
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook
      description: Delete a webhook subscription
      security:
        - BearerAuth: []
      tags:
        - Webhook Management
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The webhook ID
      responses:
        '204':
          description: Webhook deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'

  /v2/webhooks/{id}/secret/:
    get:
      operationId: getWebhookSecret
      summary: Get webhook signing secret
      description: Get the signing secret for a webhook. Use this secret to verify that incoming webhook payloads are authentic
      security:
        - BearerAuth: []
      tags:
        - Webhook Management
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The webhook ID
      responses:
        '200':
          description: Webhook signing secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    description: The webhook signing secret
                    type: string
                    examples:
                      - whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'

  /v2/webhooks/{id}/secret/rotate/:
    post:
      operationId: rotateWebhookSecret
      summary: Rotate webhook signing secret
      description: Rotate the signing secret for a webhook. Optionally provide a custom key. The new secret is not returned in the response — use the get secret endpoint to retrieve it
      security:
        - BearerAuth: []
      tags:
        - Webhook Management
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The webhook ID
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  description: An optional custom signing key. If not provided, a new key is generated automatically
                  type: string
      responses:
        '200':
          description: Signing secret rotated
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'

  /v2/webhooks/event-types/:
    get:
      operationId: listWebhookEventTypes
      summary: List webhook event types
      description: List all available event types that webhooks can subscribe to
      security:
        - BearerAuth: []
      tags:
        - Webhook Management
      responses:
        '200':
          description: List of event types
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          description: The event type identifier
                          type: string
                          examples:
                            - v1.conversation.created
                        description:
                          description: Human-readable description of the event type
                          type: string
                          examples:
                            - Sent when a new conversation is started
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'

components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          description: The webhook ID
          type: string
          readOnly: true
          examples:
            - ep_2bxE8VNtkWEMpJrMJv74FlSQmqP
        url:
          description: The URL that will receive webhook events
          type: string
          format: uri
          examples:
            - https://example.com/webhooks
        description:
          description: A description of the webhook
          type: string
          examples:
            - My production webhook
        event_filters:
          description: Event types this webhook is subscribed to. If empty, the webhook receives all events
          type: array
          items:
            type: string
          examples:
            - - v1.conversation.created
              - v1.conversation.ended
        enabled:
          description: Whether the webhook is enabled
          type: boolean
          examples:
            - true
        created_at:
          description: When the webhook was created
          type: string
          format: date-time
          readOnly: true
          examples:
            - '2026-03-12T10:00:00+00:00'
        updated_at:
          description: When the webhook was last updated
          type: string
          format: date-time
          readOnly: true
          examples:
            - '2026-03-12T10:00:00+00:00'

    EndUser:
      type: object
      properties:
        end_user_id:
          description: The unique Ada-generated id for the end user
          type:
          - string
          readOnly: true
          examples:
          - 5f7e0e2c1e7c7e000f0f9c3a
        external_id:
          description: >-
            Caller-supplied identifier that links this end user to your own system
            (for example a CRM contact ID or a phone number). Unique per AI Agent.
            Null if not set. Maximum 36 characters; values are case-insensitive.
            Available for custom channel integrations only (V1).
          type:
          - string
          - 'null'
          readOnly: true
          examples:
          - user-12345
        profile:
          description: The end user's profile information
          type: object
          properties:
            first_name:
              description: The end user's first name
              type:
              - string
              - 'null'
              examples:
              - Ada
            last_name:
              description: The end user's last name
              type:
              - string
              - 'null'
              examples:
              - Lovelace
            display_name:
              description: The end user's display name
              type:
              - string
              - 'null'
              examples:
              - Ada Lovelace
            avatar:
              description: URL to the end user's avatar image
              type:
              - string
              - 'null'
              examples:
              - https://example.com/avatars/ada.png
            email:
              description: The end user's email address
              type:
              - string
              - 'null'
              examples:
              - ada.lovelace@ada.cx
            language:
              description: The end user's language in BCP 47 format
              type:
              - string
              - 'null'
              examples:
              - en-US
            metadata:
              description: 'A dictionary of arbitrary key, value pairs assigned to
                the end user                      - `metadata` keys may only be of
                type: `string`                      - `metadata` values may only be
                one of type: `string`, `boolean`, or `integer`'
              type: object
              examples:
              - example_key1: example_string_value
                example_key2: true
                example_key3: 123
              additionalProperties: {}
            system_properties:
              description: Read-only profile information set by Ada
              type: object
              properties:
                sunshine_user_id:
                  description: The Sunshine Conversations user id for the end user
                  type:
                  - string
                  - 'null'
                  examples:
                  - 5f7e0e2c1e7c7e000f0f9c3a
                  readOnly: true
          examples:
          - end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
            profile:
              first_name: Ada
              last_name: Lovelace
              display_name: Ada Lovelace
              avatar: https://example.com/avatars/ada.png
              email: ada.lovelace@ada.cx
              language: en-US
              metadata:
                example_key1: example_string_value
                example_key2: true
                example_key3: 123
              system_properties:
                sunshine_user_id: 5f7e0e2c1e7c7e000f0f9c3a
        created_at:
          description: The date and time the end user was created
          type:
          - string
          readOnly: true
          examples:
          - '2020-09-20T00:00:00+00:00'
        updated_at:
          description: The date and time the end user was updated
          type:
          - string
          readOnly: true
          examples:
          - '2020-09-20T00:00:00+00:00'
      examples:
      - end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
        profile:
          first_name: Ada
          last_name: Lovelace
          display_name: Ada Lovelace
          avatar: https://example.com/avatars/ada.png
          email: ada.lovelace@ada.cx
          language: en-US
          metadata:
            example_key1: example_string_value
            example_key2: true
            example_key3: 123
          system_properties:
            sunshine_user_id: 5f7e0e2c1e7c7e000f0f9c3a
        created_at: '2020-09-20T00:00:00+00:00'
        updated_at: '2020-09-20T00:00:00+00:00'
    EndUsers:
      type: object
      properties:
        data:
          description: The list of end user profiles
          type:
          - array
          items:
            $ref: '#/components/schemas/EndUser'
          examples:
          - end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
            profile:
              first_name: Ada
              last_name: Lovelace
              email: null
        meta:
          $ref: '#/components/schemas/CursorPaginationMetadata'
    EndUserRequest:
      type: object
      required:
      - profile
      properties:
        external_id:
          description: >-
            Set or update the external identifier for this end user. Pass null
            to remove the current external_id. Must be unique per AI Agent;
            maximum 36 characters; must not contain < or > characters. Values
            are stored case-insensitively. Returns 409 if the external_id is
            already assigned to a different end user.
            Available for custom channel integrations only (V1).
          type:
          - string
          - 'null'
          maxLength: 36
          examples:
          - user-12345
        profile:
          description: The end user's profile information
          type: object
          properties:
            first_name:
              description: The end user's first name
              type:
              - string
              - 'null'
              examples:
              - Ada
            last_name:
              description: The end user's last name
              type:
              - string
              - 'null'
              examples:
              - Lovelace
            display_name:
              description: The end user's display name
              type:
              - string
              - 'null'
              examples:
              - Ada Lovelace
            avatar:
              description: URL to the end user's avatar image
              type:
              - string
              - 'null'
              examples:
              - https://example.com/avatars/ada.png
            email:
              description: The end user's email address
              type:
              - string
              - 'null'
              examples:
              - ada.lovelace@ada.cx
            language:
              description: The end user's language in BCP 47 format
              type:
              - string
              - 'null'
              examples:
              - en-US
            metadata:
              description: |
                A dictionary of arbitrary key, value pairs assigned to the end user.
                <br>- `metadata` keys may only be of type: `string`
                <br>- `metadata` values may only be one of type: `string`, `boolean`, or `integer`
                <br>**Note**: The total size of metadata is limited to 4KB.</br>
              type:
              - object
              - 'null'
              examples:
              - example_key1: example_string_value
                example_key2: true
                example_key3: 123
              additionalProperties: {}
            sensitive_metadata:
              description: >-
                Sensitive key-value pairs to update on the end user. Values are stored in an
                encrypted, isolated store and are never returned in any API response, dashboard
                view, conversation transcript, or LLM prompt. Values are automatically and
                permanently deleted after 24 hours.
              type:
              - object
              - 'null'
              writeOnly: true
              properties:
                fields:
                  description: >-
                    A dictionary of sensitive key-value pairs.
                    Keys must match the pattern [A-Za-z0-9_-]+.
                    Values must be non-empty strings, booleans, integers, or null.
                    Setting a key to null removes the metavariable.
                    Maximum 20 key-value pairs per request.
                  type: object
                  additionalProperties:
                    type:
                    - string
                    - boolean
                    - integer
                    - 'null'
                  maxProperties: 20
              required:
              - fields
              examples:
              - fields:
                  auth_token: eyJhbGciOiJIUzI1NiIs...
                  session_id: sess_abc123
          examples:
          - first_name: Ada
            last_name: Lovelace
            display_name: Ada Lovelace
            avatar: https://example.com/avatars/ada.png
            email: ada.lovelace@ada.cx
            language: en-US
            metadata:
              example_key1: example_string_value
              example_key2: true
              example_key3: 123
      examples:
      - profile:
          first_name: Ada
          last_name: Lovelace
          display_name: Ada Lovelace
          avatar: https://example.com/avatars/ada.png
          email: ada.lovelace@ada.cx
          language: en-US
          metadata:
            example_key1: example_string_value
            example_key2: true
            example_key3: 123
          sensitive_metadata:
            fields:
              auth_token: eyJhbGciOiJIUzI1NiIs...
              session_id: sess_abc123
    CreateEndUserRequest:
      type: object
      properties:
        external_id:
          description: >-
            Optional caller-supplied identifier (for example a CRM contact ID or
            a phone number). Maximum 36 characters; must not contain < or >
            characters. Values are stored case-insensitively. If an end user
            with this external_id already exists, that existing user is returned
            with HTTP 200 (idempotent upsert); otherwise a new end user is
            created with HTTP 201.
            Available for custom channel integrations only (V1).
          type:
          - string
          - 'null'
          maxLength: 36
          examples:
          - user-12345
        profile:
          description: The end user's profile information. Optional — omitting profile
            creates a blank end user.
          type: object
          properties:
            first_name:
              description: The end user's first name
              type:
              - string
              - 'null'
              examples:
              - Maria
            last_name:
              description: The end user's last name
              type:
              - string
              - 'null'
              examples:
              - Santos
            display_name:
              description: The end user's display name
              type:
              - string
              - 'null'
              examples:
              - Maria Santos
            avatar:
              description: URL to the end user's avatar image
              type:
              - string
              - 'null'
              examples:
              - https://example.com/avatars/maria.png
            email:
              description: The end user's email address
              type:
              - string
              - 'null'
              examples:
              - maria@example.com
            language:
              description: The end user's language in BCP 47 format
              type:
              - string
              - 'null'
              examples:
              - pt-BR
            metadata:
              description: |
                A dictionary of arbitrary key, value pairs assigned to the end user.
                <br>- `metadata` keys may only be of type: `string`
                <br>- `metadata` values may only be one of type: `string`, `boolean`, or `integer`
                <br>**Note**: The total size of metadata is limited to 4KB.</br>
              type:
              - object
              - 'null'
              examples:
              - region: latam
                plan_type: enterprise
              additionalProperties: {}
            sensitive_metadata:
              description: >-
                Sensitive key-value pairs to associate with the end user at creation time.
                Values are stored in an encrypted, isolated store and are never returned in
                any API response, dashboard view, conversation transcript, or LLM prompt.
                Values are automatically and permanently deleted after 24 hours.
              type:
              - object
              - 'null'
              writeOnly: true
              properties:
                fields:
                  description: >-
                    A dictionary of sensitive key-value pairs.
                    Keys must match the pattern [A-Za-z0-9_-]+.
                    Values must be non-empty strings, booleans, integers, or null.
                    Maximum 20 key-value pairs per request.
                    Keys must not overlap with keys in the sibling metadata field.
                  type: object
                  additionalProperties:
                    type:
                    - string
                    - boolean
                    - integer
                    - 'null'
                  maxProperties: 20
              required:
              - fields
              examples:
              - fields:
                  auth_token: eyJhbGciOiJIUzI1NiIs...
                  session_id: sess_abc123
      examples:
      - profile:
          first_name: Maria
          last_name: Santos
          email: maria@example.com
          language: pt-BR
          metadata:
            region: latam
            plan_type: enterprise
          sensitive_metadata:
            fields:
              auth_token: eyJhbGciOiJIUzI1NiIs...
              session_id: sess_abc123
    EndUserCreatedWebhookPayload:
      properties:
        type:
          description: The webhook event type description
          type:
          - string
          readOnly: false
          examples:
          - v1.end_user.created
        timestamp:
          description: The timestamp for when the event was generated. Uses millisecond
            precision to help with event ordering needs.
          type:
          - string
          readOnly: false
          examples:
          - '2024-01-17T22:23:35.835'
        data:
          type: object
          description: The webhook event data
          allOf:
          - $ref: '#/components/schemas/EndUser'
          - type: object
            properties:
              end_user_id:
                description: The unique Ada-generated id for the end user
                type:
                - string
                examples:
                - 5f7e0e2c1e7c7e000f0f9c3a
                readOnly: false
              created_at:
                description: The date and time the end user was created
                type:
                - string
                examples:
                - '2020-09-20T00:00:00+00:00'
                readOnly: false
              updated_at:
                description: The date and time the end user was updated
                type:
                - string
                examples:
                - '2020-09-20T00:00:00+00:00'
                readOnly: false
          examples:
          - type: v1.end_user.created
            timestamp: '2020-09-20T00:00:00+00:00'
            data:
              end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
              profile:
                first_name: Ada
                last_name: Lovelace
                display_name: Ada Lovelace
                avatar: https://example.com/avatars/ada.png
                email: ada.lovelace@ada.cx
                language: en-US
                metadata:
                  example_key1: example_string_value
                  example_key2: true
                  example_key3: 123
                  system_properties:
                    sunshine_user_id: 5f7e0e2c1e7c7e000f0f9c3a
              created_at: '2020-09-20T00:00:00+00:00'
              updated_at: '2020-09-20T00:00:00+00:00'
        tags:
          description: A list of tags that Ada provides. You can use tags to filter
            webhook events in the Ada dashboard. Includes the `end_user_id` value
            for the webhook payload by default. Ada may add additional tags at any
            time.
          type:
          - array
          items:
            type:
            - string
          examples:
          - - 5f7e0e2c1e7c7e000f0f9c3a
            - example_tag
      examples:
      - type: v1.end_user.created
        timestamp: '2020-09-20T00:00:00+00:00'
        data:
          end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
          profile:
            first_name: Ada
            last_name: Lovelace
            display_name: Ada Lovelace
            avatar: https://example.com/avatars/ada.png
            email: ada.lovelace@ada.cx
            language: en-US
            metadata:
              example_key1: example_string_value
              example_key2: true
              example_key3: 123
            system_properties:
              sunshine_user_id: 5f7e0e2c1e7c7e000f0f9c3a
          created_at: '2020-09-20T00:00:00+00:00'
          updated_at: '2020-09-20T00:00:00+00:00'
        tags:
        - 5f7e0e2c1e7c7e000f0f9c3a
    EndUserUpdatedWebhookPayload:
      properties:
        type:
          description: The webhook event type description
          type:
          - string
          readOnly: false
          examples:
          - v1.end_user.updated
        timestamp:
          description: The timestamp for when the event was generated. Uses millisecond
            precision to help with event ordering needs.
          type:
          - string
          readOnly: false
          examples:
          - '2020-09-20T00:00:00+00:00'
        data:
          description: The webhook event data
          type: object
          allOf:
          - $ref: '#/components/schemas/EndUser'
          - type: object
            properties:
              end_user_id:
                type:
                - string
                description: The unique Ada-generated id for the end user
                examples:
                - 5f7e0e2c1e7c7e000f0f9c3a
                readOnly: false
              created_at:
                type:
                - string
                description: The date and time the end user was created
                examples:
                - '2020-09-20T00:00:00+00:00'
                readOnly: false
              updated_at:
                type:
                - string
                description: The date and time the end user was updated
                examples:
                - '2020-09-20T00:00:00+00:00'
                readOnly: false
          examples:
          - end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
            profile:
              first_name: Ada
              last_name: Lovelace
              display_name: Ada Lovelace
              avatar: https://example.com/avatars/ada.png
              email: ada.lovelace@ada.cx
              language: en-US
              metadata:
                example_key1: example_string_value
                example_key2: true
                example_key3: 123
                system_properties:
                  sunshine_user_id: 5f7e0e2c1e7c7e000f0f9c3a
            created_at: '2020-09-20T00:00:00+00:00'
            updated_at: '2020-09-20T00:00:00+00:00'
        tags:
          description: A list of tags that Ada provides. You can use tags to filter
            webhook events in the Ada dashboard. Includes the `end_user_id` value
            for the webhook payload by default. Ada may add additional tags at any
            time.
          type:
          - array
          items:
            type:
            - string
          examples:
          - - 5f7e0e2c1e7c7e000f0f9c3a
            - example_tag
      examples:
      - type: v1.end_user.updated
        timestamp: '2020-09-20T00:00:00+00:00'
        data:
          end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
          profile:
            first_name: Ada
            last_name: Lovelace
            display_name: Ada Lovelace
            avatar: https://example.com/avatars/ada.png
            email: ada.lovelace@ada.cx
            language: en-US
            metadata:
              example_key1: example_string_value
              example_key2: true
              example_key3: 123
            system_properties:
              sunshine_user_id: 5f7e0e2c1e7c7e000f0f9c3a
          created_at: '2020-09-20T00:00:00+00:00'
          updated_at: '2020-09-20T00:00:00+00:00'
        tags:
        - 5f7e0e2c1e7c7e000f0f9c3a
    KnowledgeSourceResponse:
      type: object
      properties:
        id:
          description: A unique identifier for the knowledge source
          type: string
          examples:
          - 5df263b7db5a7e6ea03fae9b
        external_id:
          description: An external identifier for the knowledge source
          type:
          - string
          - 'null'
          examples:
          - external_id_1
        name:
          description: The name of the knowledge source
          type: string
          minLength: 1
          examples:
          - Ada Knowledge Base
        metadata:
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the knowledge source.
          type:
          - object
          - 'null'
          examples:
          - example_key1: example_string_value
            example_key2: true
            example_key3: 123
        created:
          description: The date the knowledge source was created
          type: string
          format: date-time
          examples:
          - '2020-09-20T00:00:00+00:00'
        updated:
          description: The date the knowledge source was last updated
          type: string
          format: date-time
          examples:
          - '2020-09-20T00:00:00+00:00'
        last_sync:
          description: The date the knowledge source was last synchronized
          type: string
          format: date-time
          examples:
            - '2020-09-20T00:00:00+00:00'
      required:
      - id
      - name
    KnowledgeSourceCreateRequest:
      type: object
      additionalProperties: false
      properties:
        id:
          description: A unique identifier for the knowledge source
          type: string
          minLength: 1
          maxLength: 160
          examples:
          - 5df263b7db5a7e6ea03fae9b
        name:
          description: The name of the knowledge source
          type: string
          minLength: 1
          examples:
          - Ada Knowledge Base
        metadata:
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the knowledge source.
          type:
          - object
          - 'null'
          examples:
          - example_key1: example_string_value
            example_key2: true
            example_key3: 123
      required:
      - id
      - name
    KnowledgeSourceUpdateRequest:
      type: object
      additionalProperties: false
      properties:
        external_id:
          description: A unique identifier for the knowledge source
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 160
          examples:
          - 5df263b7db5a7e6ea03fae9b
        name:
          description: The name of the knowledge source
          type: string
          minLength: 1
          examples:
          - Ada Knowledge Base
        metadata:
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the knowledge source.
          type:
          - object
          - 'null'
          examples:
          - example_key1: example_string_value
            example_key2: true
            example_key3: 123
    KnowledgeArticleUpsertResponse:
      type: object
      properties:
        success:
          description: Whether the article was successfully created/updated
          type: boolean
          examples:
          - true
        created:
          description: '`True` if a new article was created, `false` if an existing
            article was updated'
          type: boolean
          examples:
          - true
        id:
          description: A unique identifier for the article
          type: string
          minLength: 1
          maxLength: 160
          examples:
          - 5df263b7db5a7e6ea03fae9b
      required:
      - id
    KnowledgeArticleResponse:
      type: object
      properties:
        id:
          description: A unique identifier for the article
          type: string
          minLength: 1
          maxLength: 160
          examples:
          - 5df263b7db5a7e6ea03fae9b
        name:
          description: The name or title of the article
          type: string
          minLength: 1
          maxLength: 255
          examples:
          - How to reset your password
        content:
          description: The content of the article in markdown format
          type: string
          minLength: 1
          examples:
          - '# How to reset your password\n\n1. Go to the login page\n2. Click on
            the "Forgot password" link\n3. Follow the instructions'
        url:
          description: The url of the article
          type:
          - string
          - 'null'
          format: url
          examples:
          - https://example.com/article
        knowledge_source_id:
          description: The id of the `knowledge_source` the article belongs to
          type:
          - string
          - 'null'
          examples:
          - 5df263b7db5a7e6ea03fae9b
        language:
          $ref: '#/components/schemas/ArticleLanguage'
        tag_ids:
          description: A list of ids for the tags associated with the article
          type: array
          maxItems: 100
          items:
            type: string
            minLength: 1
          examples:
          - - 5df263b7db5a7e6ea03fae9b
            - 5df263b7db5a7e6ea03fae9c
        created:
          description: The date the article was created in Ada
          type: string
          format: date-time
          examples:
          - '2020-09-20T00:00:00+00:00'
        updated:
          description: The date the article was last updated in Ada
          type: string
          format: date-time
          examples:
          - '2020-09-20T00:00:00+00:00'
        external_created:
          description: The date the article was created in the source system
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2020-09-20T00:00:00+00:00'
        external_updated:
          description: The date the article was last updated in the source system
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2020-09-20T00:00:00+00:00'
        enabled:
          description: Whether the article should be referenced during response generation,
            defaults to `true`
          type: boolean
          examples:
          - true
        metadata:
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the article.
          type:
          - object
          - 'null'
          examples:
          - example_key1: example_string_value
            example_key2: true
            example_key3: 123
      required:
      - content
      - id
      - name
    KnowledgeArticleUpsertRequest:
      type: object
      additionalProperties: false
      properties:
        id:
          description: A unique identifier for the article
          type: string
          minLength: 1
          maxLength: 160
          examples:
          - 5df263b7db5a7e6ea03fae9b
        name:
          description: The name or title of the article
          type: string
          minLength: 1
          maxLength: 255
          examples:
          - How to reset your password
        content:
          description: The content of the article in markdown format
          type: string
          minLength: 1
          examples:
          - '# How to reset your password\n\n1. Go to the login page\n2. Click on
            the "Forgot password" link\n3. Follow the instructions'
        url:
          description: The url of the article
          type:
          - string
          - 'null'
          format: url
          examples:
          - https://example.com/article
        knowledge_source_id:
          description: The id of the `knowledge_source` the article belongs to
          type: string
          examples:
          - 5df263b7db5a7e6ea03fae9b
        tag_ids:
          description: A list of ids for the tags associated with the article
          type: array
          maxItems: 100
          items:
            type: string
            minLength: 1
          examples:
          - - 5df263b7db5a7e6ea03fae9b
            - 5df263b7db5a7e6ea03fae9c
        language:
          description: The IETF BCP 47 language code for the article, defaults to `en`
          type: string
          examples:
            - en-CA
            - en-GB
            - en
            - fr-CA
            - fr-FR
        external_created:
          description: The date the article was created in the source system
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2020-09-20T00:00:00+00:00'
        external_updated:
          description: The date the article was last updated in the source system
          type:
          - string
          - 'null'
          format: date-time
          examples:
          - '2020-09-20T00:00:00+00:00'
        enabled:
          description: Whether the article should be referenced during response generation,
            defaults to `true`
          type: boolean
          examples:
          - true
        metadata:
          description: A dictionary of arbitrary key,value pairs.                     This
            data is not used by Ada, but can be used by the client to store additional
            information about                     the article.
          type:
          - object
          - 'null'
          examples:
          - example_key1: example_string_value
            example_key2: true
            example_key3: 123
      required:
      - content
      - id
      - knowledge_source_id
      - name
    ArticleTag:
      type: object
      additionalProperties: false
      properties:
        id:
          description: A unique identifier for the tag
          type: string
          minLength: 1
          maxLength: 40
          examples:
          - 5df263b7db5a7e6ea03fae9b
        name:
          description: The name of the tag
          type: string
          minLength: 1
          maxLength: 40
          examples:
          - password_reset
      required:
      - id
      - name
    ArticleTagUpsertResponse:
      type: object
      properties:
        success:
          description: Whether the article tag was successfully created/updated
          type: boolean
          examples:
          - true
        created:
          description: '`True` if a new article tag was created, `false` if an existing
            article tag was updated'
          type: boolean
          examples:
          - true
        id:
          description: The id of the article tag
          type: string
          examples:
          - 5df263b7db5a7e6ea03fae9b
      required:
      - created
      - id
      - success
    ArticleLanguage:
      description: The ISO 639-1 language code of the article, defaults to `en`
      type: string
      enum:
      - ar
      - zh
      - zh-tw
      - da
      - nl
      - en
      - fi
      - fr
      - de
      - he
      - hi
      - id
      - in
      - it
      - ja
      - ko
      - ms
      - false
      - pt
      - pa
      - ru
      - es
      - sv
      - tl
      - ta
      - th
      - tr
      - vi
      - ht
      - my
      - km
      - bg
      - ro
      - el
      - hu
      - pl
      - cs
      - et
      - hr
      - lt
      - lv
      - sl
      - sk
      - is
      - be
      - uk
      - ca
      - sq
      - bs
      - sr
      - kk
      examples:
      - en
    PaginationMetadata:
      type: object
      properties:
        next_page_url:
          description: The URL to the next page of results
          type:
            - string
            - 'null'
          default: null
          examples:
            - https://example.ada.support/api/v2/api-name?cursor=6658f91ea88ff7e389eff34d
      examples:
        - next_page_url: https://example.ada.support/api/v2/api-name?cursor=6658f91ea88ff7e389eff34d
    CursorPaginationMetadata:
      description: Metadata returned with the results including but not limited to
        a link to the next page of data
      type: object
      properties:
        next_page_url:
          type: string
          format: url
          description: Link to the next page of data using a cursor value
          examples:
          - https://example.ada.support/api/v2/end-users/?cursor=65a17e3f43bec88e2792d0eb
      examples:
      - next_page_url: https://example.ada.support/api/v2/end-users/?cursor=65a17e3f43bec88e2792d0eb
    Errors:
      type: object
      properties:
        errors:
          description: A list of errors
          type:
          - array
          items:
            type: object
            properties:
              type:
                description: The error type
                type:
                - string
                examples:
                - unauthorized
              message:
                description: The error message
                type:
                - string
                examples:
                - 401 Unauthorized: The server could not verify that you are authorized
                    to access the URL requested
              details:
                description: Extra information about the error
                type:
                - string
                - 'null'
                examples:
                - The requested resource with id <id> was not found
            examples:
            - type: resource_not_found
              message: The requested resource was not found
              details: The requested resource with id 123456abcdef was not found
            required:
            - type
            - message
          examples:
          - errors:
            - type: resource_not_found
              message: The requested resource was not found
              details: The requested resource with id 123456abcdef was not found
      required:
      - errors

    PlatformIntegrationInstallation:
      type: object
      properties:
        id:
          description: The unique identifier for the integration installation
          type: string
          format: id
          examples:
            - 5df263b7db5a7e6ea03fae9b
        platform_integration_id:
          description: The unique identifier for the integration
          type: string
          format: id
          examples:
            - 5df263b7db5a7e6ea03fae9b
        created:
          description: The date and time the installation was created
          type: string
          format: date-time
          examples:
            - '2020-09-20T00:00:00+00:00'
        updated:
          description: The date and time the installation was last updated
          type: string
          format: date-time
          examples:
            - '2020-09-20T00:00:00+00:00'
        configuration:
          description: The configuration settings for the integration
          type: object
          examples:
            - credentials:
                helpCenterUrl: "https://example.com"
                consumerKey: "123"
                consumerSecret: "456"
        status:
          description: The current state of the integration installation (incomplete, complete)
          type: string
          examples:
            - complete
    PlatformIntegrationInstallationUpdateRequest:
      type: object
      additionalProperties: false
      properties:
        status:
          description: The new status of the installation
          type: string
          enum:
            - complete
            - incomplete
          examples:
            - complete
    IntegrationCommonFields:
      type: object
      properties:
        name:
          description: The name of the integration
          type: string
          minLength: 1
          maxLength: 160
          examples:
            - Connect to Cool Shop Knowledge Hub
        description:
          description: A description of what the integration does and how to use it
          type: string
          minLength: 1
          examples:
            - Connect to Cool Shop Knowledge Hub to sync articles with your AI Agent's knowledge base
        author:
          description: The name of the integration developer
          type: string
          minLength: 1
          maxLength: 160
          examples:
            - Cool Shop
        contact:
          description: The URL or email address where users of the integration can reach out for support
          type: string
          minLength: 1
          examples:
            - "help@coolshop.support"
        uninstallation_url:
          description: The `delete` endpoint that initiates the uninstallation flow for the integration
          type: string
          minLength: 1
          format: url
          examples:
            - "http://coolshop.com/uninstall"
        oauth_callback_url:
          description: The `get` endpoint that will be invoked after OAuth authorization
          type: string
          minLength: 1
          format: url
          examples:
            - "http://coolshop.com/"
        tags:
          description: A list of tags that describe the type of integration
          type: array
          items:
            type: string
            minLength: 1
            enum:
              - "knowledge"
          examples:
            - [ "knowledge" ]
        error_codes:
          type:
            - object
            - 'null'
          description: An object containing error codes and their corresponding error message the integration may return to the OAuth failure page to be displayed
          examples:
            - { "error_403": "Unauthorized", "error_404": "Not Found" }
        scopes:
          description: The list of OAuth token permissions the integration requests when installed
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
          examples:
            - [ "articles:read", "knowledge_sources:write" ]
        configuration_fields:
          description: A json-schema describing the settings fields that a user should be presented with when installing the integration
          type: object
          examples:
            - title: Connect to Cool Shop Knowledge Hub
              type: object
              description: "Complete this form to integrate your Knowledge Hub with your AI Agent"
              required: [ "credentials" ]
              properties:
                credentials:
                  type: object
                  title: My Knowledge Hub credentials
                  description: "The following information is found in your Cool Shop admin center"
                  properties:
                    knowledgeHubUrl:
                      type: string
                      title: Knowledge Hub URL
                      description: 'The URL of your Knowledge Hub'
                    secretKey:
                      type: string
                      title: Secret key
                      description: 'Find your Knowledge Hub secret key on the Knowledge Hub Management page'
                      format: password
                  required:
                    - knowledgeHubUrl
                    - secretKey
    IntegrationIdentifierField:
      type: string
      description: JMESPath describing which of the fields in `configuration_fields` is the best human-friendly field to use to identify a specific installation (e.g., account name)
      examples:
        - "credentials.knowledgeHubUrl"
    IntegrationIconUrl:
      type:
        - string
        - 'null'
      minLength: 1
      format: url
      description: The URL of the icon that should be displayed with your integration
      examples:
        - "https://example.com/icon.png"
    IntegrationCallToAction:
      type:
        - string
        - 'null'
      minLength: 1
      description: The call to action text
      examples:
        - Connect to Cool Shop Knowledge Hub
    PlatformIntegrationCreateRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/IntegrationCommonFields'
      properties:
        identifier_field_path:
          $ref: '#/components/schemas/IntegrationIdentifierField'
        icon_url:
          $ref: '#/components/schemas/IntegrationIconUrl'
        call_to_action:
          $ref: '#/components/schemas/IntegrationCallToAction'
      required:
        - name
        - description
        - author
        - contact
        - uninstallation_url
        - oauth_callback_url
        - tags
        - scopes
        - configuration_fields
        - identifier_field_path
    PlatformIntegrationUpdateRequest:
      type: object
      allOf:
        - $ref: '#/components/schemas/IntegrationCommonFields'
      properties:
        identifier_field_path:
          $ref: '#/components/schemas/IntegrationIdentifierField'
        icon_url:
          $ref: '#/components/schemas/IntegrationIconUrl'
        call_to_action:
          $ref: '#/components/schemas/IntegrationCallToAction'
    PlatformIntegration:
      type: object
      allOf:
        - $ref: '#/components/schemas/IntegrationCommonFields'
      properties:
        id:
          description: The unique identifier for the integration
          type: string
          examples:
            - 5df263b7db5a7e6ea03fae9b
        status:
          description: The current state of the integration (development, approved, archived)
          type: string
          examples:
            - development
        created:
          description: The date the integration was created
          type: string
          format: date-time
          examples:
            - '2020-09-20T00:00:00+00:00'
        updated:
          description: The date the integration was last updated
          type: string
          format: date-time
          examples:
            - '2020-09-20T00:00:00+00:00'
        identifier_field_path:
          $ref: '#/components/schemas/IntegrationIdentifierField'
        icon_url:
          $ref: '#/components/schemas/IntegrationIconUrl'
        call_to_action:
          $ref: '#/components/schemas/IntegrationCallToAction'
      required:
        - id
        - name
        - description
        - author
        - contact
        - uninstallation_url
        - oauth_callback_url
        - tags
        - scopes
        - status
        - configuration_fields
        - identifier_field_path

    EmailConversationCreateRequest:
      type: object
      properties:
        name:
          description: The customer's full name
          type: string
          examples:
          - Firstname Lastname
        subject:
          description: The subject of the customer's inquiry; used as the subject
            for the AI Agent's reply
          type: string
          examples:
          - Email subject
        reply_to:
          description: The customer's email address
          type: string
          examples:
          - user@mail.com
        text:
          description: The customer's inquiry, limited to 10 KB
          type: string
          examples:
          - Email body
        reply_as:
          description: The company email address you want to use to reply to the customer.
            Defaults to the Ada provided email address.
          type: string
          examples:
          - help@company.com
        cc:
          description: >-
            The email addresses in the email's CC field
          type: array
          items:
            type: string
          examples:
          - ["user2@mail.com", "user3@mail.com"]
        metadata:
          description: Any metadata associated with the conversation, up to 4 KB.
            All metadata passed through this field will appear as metavariables in
            your dashboard.
          type: object
          keys:
            type: string
          values:
            type:
            - string
            - boolean
            - number
          examples:
          - ticket_id: '1001'
      required:
      - name
      - subject
      - reply_to
    EmailConversationCreateResponse:
      type: object
      properties:
        conversation_id:
          description: The Ada-generated conversation id
          type: string
          readOnly: true
          examples:
          - 5df263b7db5a7e6ea03fae9b

    BaseChannel:
      type: object
      properties:
        id: &channel-id-field
          description: The channel ID
          type: string
          readOnly: true
          examples:
            - native.email
            - 5df263b7db5a7e6ea03fae9b
        type: &channel-type-field
          description: The type of the channel
          type: string
          readOnly: true
          examples:
            - native
            - custom
        name:
          description: The name of the channel
          type: string
          examples:
            - My Custom Channel
        description:
          description: A description of the channel
          type: string
          examples:
            - A custom messaging channel for my AI Agent
        modality:
          description: The modality of the channel
          type: string
          enum:
            - messaging
            - email
            - voice
          examples:
            - messaging
            - email
            - voice
      required:
        - name
        - description
        - modality

    NativeChannel:
      allOf:
        - $ref: '#/components/schemas/BaseChannel'
        - type: object
          properties:
            id:
              <<: *channel-id-field
              examples:
                - native.email
            type:
              <<: *channel-type-field
              enum:
                - native
              examples:
                - native

    CustomChannel:
      allOf:
        - $ref: '#/components/schemas/BaseChannel'
        - type: object
          properties:
            id:
              <<: *channel-id-field
              format: id
              examples:
                - 5df263b7db5a7e6ea03fae9b
            type:
              <<: *channel-type-field
              enum:
                - custom
              examples:
                - custom
            metadata:
              description: |
                A dictionary of key, value pairs assigned to the channel. Metadata may not exceed 4KB total.
                - `metadata` keys may only be of type: `string`
                - `metadata` values may only be one of type: `string`, `boolean`, `integer`, or `number` (float)
              type: object
              examples:
                - example_key1: example_string_value
                  example_key2: true
                  example_key3: 123
                  example_key4: 0.95
              additionalProperties:
                type:
                  - string
                  - boolean
                  - integer
                  - number
                minimum: -9223372036854775808
                maximum: 9223372036854775807
            created_at:
              description: The date and time the channel was created
              type: string
              format: date-time
              readOnly: true
              examples:
                - 2020-09-20T00:00:00+00:00

    Channel:
      oneOf:
        - $ref: '#/components/schemas/CustomChannel'
        - $ref: '#/components/schemas/NativeChannel'
      discriminator:
        propertyName: type
        mapping:
          custom: '#/components/schemas/CustomChannel'
          native: '#/components/schemas/NativeChannel'

    Conversation:
      type: object
      properties:
        id:
          description: The ID of the conversation
          type: string
          format: id
          readOnly: true
          examples:
            - 5df263b7db5a7e6ea03fae9b
        channel_id:
          description: The ID of the channel
          type: string
          examples:
            - 5df263b7db5a7e6ea03fae9b
            - bmF0aXZlLWNoYXQtNjkwOTI3Nzk1YzA0ZjFhOGM1NTI0NmIx
        end_user_id:
          description: The ID of the end user participating in the conversation
          type: string
          format: id
          examples:
            - 5df263b7db5a7e6ea03fae9b
        status:
          description: The status of the conversation
          type: string
          readOnly: true
          enum:
            - active
            - ended
          examples:
            - active
        created_at:
          description: The date and time the conversation was created
          type: string
          readOnly: true
          examples:
            - '2020-09-20T00:00:00+00:00'
        updated_at:
          description: The date and time the conversation was last updated
          type: string
          readOnly: true
          examples:
            - '2020-09-20T00:00:00+00:00'
        metadata:
          description: |
           A dictionary of key value pairs assigned to the conversation. Note: This metadata does not create or set Ada metavariables. To create or update metavariables, use the End Users API.
            - `metadata` keys may only be of type: `string`
            - `metadata` values may only be one of type: `string`, `boolean`, `integer`, or `number` (float)
          type: object
          examples:
            - pass: example_string_value
              initial_url: https://example.com
              locale: en-CA
              confidence: 0.95
          additionalProperties:
            type:
              - string
              - boolean
              - integer
              - number
            minimum: -9223372036854775808
            maximum: 9223372036854775807

    AttachmentUploadResponse:
      type: object
      properties:
        url:
          description: Presigned URL to access the uploaded file (valid for 7 days)
          type: string
          format: uri
          readOnly: true
          examples:
            - https://s3.amazonaws.com/bucket/conversations/5df263b7db5a7e6ea03fae9b/5df263b7db5a7e6ea03fae9b/a1b2c3d4-e5f6-7890-abcd-ef1234567890/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...
        mime_type:
          description: MIME type of the uploaded file
          type: string
          readOnly: true
          examples:
            - application/pdf
            - image/png
            - text/plain
        filename:
          description: Name of the uploaded file
          type: string
          readOnly: true
          examples:
            - document.pdf
            - screenshot.png
            - notes.txt
      required:
        - url
        - mime_type
        - filename
      examples:
        - url: https://s3.amazonaws.com/bucket/conversations/5df263b7db5a7e6ea03fae9b/5df263b7db5a7e6ea03fae9b/a1b2c3d4-e5f6-7890-abcd-ef1234567890/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256
          mime_type: application/pdf
          filename: document.pdf

    ConversationCreateRequest:
      type: object
      properties:
        channel_id:
          description: The ID of the channel to create a conversation in
          type:
            - string
          format: id
          examples:
            - 5df263b7db5a7e6ea03fae9b
        end_user_id:
          description: The ID of the end user participating in the conversation. If not provided, the system will create a new end user automatically.
          type:
            - string
          format: id
          examples:
            - 5df263b7db5a7e6ea03fae9b
        metadata:
          description: |
           A dictionary of key value pairs assigned to the conversation. Note: This metadata does not create or set Ada metavariables. To create or update metavariables, use the End Users API.
            - `metadata` keys may only be of type: `string`
            - `metadata` values may only be one of type: `string`, `boolean`, `integer`, or `number` (float)
          type: object
          examples:
            - pass: example_string_value
              initial_url: https://example.com
              locale: en-CA
              confidence: 0.95
          additionalProperties:
            type:
              - string
              - boolean
              - integer
              - number
            minimum: -9223372036854775808
            maximum: 9223372036854775807
      required:
        - channel_id

    ConversationPatchRequest:
      type: object
      required:
        - metadata
      properties:
        metadata:
          description: |
            A dictionary of key, value pairs to add to the conversation metadata additively
            - `metadata` keys may only be of type: `string`
            - `metadata` values may only be one of type: `string`, `boolean`, `integer`, or `number` (float)
            - `metadata` keys with a `null` value will be removed from the conversation metadata
          type: object
          examples:
            - pass: example_string_value
              initial_url: https://example.com
              locale: en-CA
              confidence: 0.95
          additionalProperties:
            type:
              - string
              - boolean
              - integer
              - number
              - 'null'
            minimum: -9223372036854775808
            maximum: 9223372036854775807

    Message:
      type: object
      properties:
        id:
          description: The ID of the message
          type: string
          format: id
          readOnly: true
          examples:
            - 5df263b7db5a7e6ea03fae9b
        conversation_id:
          description: The ID of the conversation
          type: string
          format: id
          readOnly: true
          examples:
            - 5df263b7db5a7e6ea03fae9b
        author:
          $ref: '#/components/schemas/ConversationMessageAuthor'
        content:
          description: The message content
          oneOf:
            - $ref: '#/components/schemas/TextContent'
            - $ref: '#/components/schemas/FileContent'
          discriminator:
            propertyName: type
            mapping:
              text: '#/components/schemas/TextContent'
              file: '#/components/schemas/FileContent'
          examples:
            - type: text
              body: "Hello, how can I help you?"
            - type: file
              url: "https://example.com/files/document.pdf"
              mime_type: "application/pdf"
              filename: "document.pdf"
        created_at:
          description: The date and time the message was created
          type: string
          format: date-time
          readOnly: true
          examples:
            - 2020-09-20T00:00:00+00:00
        updated_at:
          description: The date and time the message was updated
          type: string
          format: date-time
          readOnly: true
          examples:
            - 2020-09-20T00:00:00+00:00

    MessageCreateRequest:
      type: object
      properties:
        author:
          $ref: '#/components/schemas/ConversationMessageAuthor'
        content:
          description: The message content
          oneOf:
            - $ref: '#/components/schemas/TextContent'
            - $ref: '#/components/schemas/FileContent'
          discriminator:
            propertyName: type
            mapping:
              text: '#/components/schemas/TextContent'
              file: '#/components/schemas/FileContent'
          examples:
            - type: text
              body: "Hello, how can I help you?"
            - type: file
              url: "https://example.com/files/document.pdf"
              mime_type: "application/pdf"
              filename: "document.pdf"
      required:
        - author
        - content

    TextContent:
      description: The content of the text message
      type: object
      properties:
        type: &content-type-field
          description: The type of the message
          type: string
          enum:
            - text
          examples:
            - text
        body:
          description: The body of the message
          type: string
          examples:
            - "I need help with my order"
      required:
        - type
        - body
      examples:
        - type: text
          body: "I need help with my order"

    LinkContent:
      description: The content of a standalone link style messages, such as CSAT
      type: object
      properties:
        type:
          <<: *content-type-field
          enum:
            - link
          examples:
            - link
        url:
          description: The link's URL
          type: string
          examples:
            - "https://example.com/csat"
        link_text:
          description: Text that can be used to display the link
          type:
            - string
            - 'null'
          examples:
            - "Rate your experience"
      examples:
        - type: link
          url: "https://example.com/csat"
          link_text: "Rate your experience"

    FileContent:
      description: The content of a file message
      type: object
      properties:
        type:
          <<: *content-type-field
          enum:
            - file
          examples:
            - file
        url:
          type: string
          format: uri
          description: Presigned URL from the attachment upload endpoint (valid for 7 days)
          examples:
            - "https://example.com/files/document.pdf"
        mime_type:
          type: string
          description: MIME type of the file
          examples:
            - "application/pdf"
        filename:
          type: string
          description: Name of the file
          examples:
            - "document.pdf"
      required:
        - type
        - url
        - mime_type
        - filename
      examples:
        - type: file
          url: "https://example.com/files/document.pdf"
          mime_type: "application/pdf"
          filename: "document.pdf"

    MessageLogs:
      type: object
      properties:
        type:
          type: string
          description: The type of the message
          readOnly: true
          enum:
            - message_logs
          examples:
            - message_logs
        message_id:
          description: The ID of the message log
          type:
            - string
          examples:
            - 5df263b7db5a7e6ea03fae9b
        created_at:
          description: The date and time the message was created
          type:
            - string
          examples:
            - "2020-09-20T00:00:00+00:00"
        author:
          description: Information about the message author
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
              description: >-
                If the role is `end_user`, the ID of the end user. If the role is `ai_agent` or `human_agent`, this is null.
              examples:
                - 5df263b7db5a7e6ea03fae9b
                - null
            role:
              description: The author's role
              type: string
              enum:
                - end_user
                - ai_agent
                - human_agent
              examples:
                - end_user
            avatar:
              description: The URL of the author's avatar
              type:
                - string
                - "null"
              examples:
                - https://www.gravatar.com
            display_name:
              description: The author's display name
              type:
                - string
                - "null"
              examples:
                - Ada Lovelace
          examples:
            - id: 5df263b7db5a7e6ea03fae9b
              role: end_user
              avatar: https://www.gravatar.com
              display_name: Ada Lovelace
        content:
          description: >-
            The message content. The structure varies based on the `type` field.
            Supported types: text, link, file.
          oneOf:
            - $ref: '#/components/schemas/TextContent'
            - $ref: '#/components/schemas/LinkContent'
            - $ref: '#/components/schemas/FileContent'
          discriminator:
            propertyName: type
            mapping:
              text: '#/components/schemas/TextContent'
              link: '#/components/schemas/LinkContent'
              file: '#/components/schemas/FileContent'
          examples:
            - type: text
              body: "I need help with my order"

    MessageEvents:
      oneOf:
        - $ref: '#/components/schemas/MessageLogs'
      discriminator:
        propertyName: type
        mapping:
          message_logs: '#/components/schemas/MessageLogs'

    MessageList:
      type: object
      properties:
        data:
          description: List of messages in the conversation
          type: array
          items:
            $ref: '#/components/schemas/MessageEvents'
          examples:
            - - type: message_logs
                message_id: 6900e297d458517e4b15787d
                created_at: 2025-10-28T15:34:41+00:00
                author:
                  id: null
                  role: ai_agent
                  display_name: null
                  avatar: null
                content:
                  type: text
                  body: "Hello! I'm an AI Agent, here to assist with any questions you may have."
              - type: message_logs
                message_id: 6900e299d458517e4b157881
                created_at: 2025-10-28T15:34:49+00:00
                author:
                  id: 6900e28ff6f931ca8672f6dd
                  role: end_user
                  display_name: null
                  avatar: null
                content:
                  type: text
                  body: "this is just a test"
              - type: message_logs
                message_id: 6900e2a2d458517e4b157887
                created_at: 2025-10-28T15:35:05+00:00
                author:
                  id: null
                  role: ai_agent
                  display_name: null
                  avatar: null
                content:
                  type: link
                  url: "https://example.com/csat?conversation_id=123"
                  link_text: "Rate your experience"
        meta:
          $ref: '#/components/schemas/PaginationMetadata'
      required:
        - data
        - meta

    ConversationMessageAuthor:
      description: Information about the message author
      type: object
      properties:
        id:
          type:
            - string
            - "null"
          description: >-
            The ID of the user that will be participating in the
            conversation. Required when the role is `end_user`.
          examples:
            - 5df263b7db5a7e6ea03fae9b
        role:
          type: string
          enum:
            - end_user
            - human_agent
          description: The author's role
          examples:
            - end_user
        avatar:
          description: The URL of the author's avatar
          type:
            - string
            - "null"
          examples:
            - https://www.gravatar.com
        display_name:
          description: The author's display name. Required when the role is `human_agent`.
          type:
            - string
            - "null"
          examples:
            - Ada Lovelace
      required:
        - role
      examples:
        - id: 5df263b7db5a7e6ea03fae9b
          role: end_user
          avatar: https://www.gravatar.com
          display_name: Ada Lovelace
        - id: null
          role: human_agent
          avatar: https://www.gravatar.com
          display_name: Ada Lovelace

    ConversationCreatedWebhookPayload:
      properties:
        type:
          description: The webhook event type
          type: string
          enum:
            - v1.conversation.created
          examples:
            - v1.conversation.created
        timestamp:
          description: The timestamp for when the event was generated (uses millisecond precision to help with event ordering)
          type: string
          examples:
            - '2020-09-20T00:00:00+00:00'
        data:
          description: The webhook event data
          type: object
          properties:
            conversation_id:
              description: The ID of the conversation
              type: string
              examples:
                - 5df263b7db5a7e6ea03fae9b
            channel_id:
              description: The ID of the channel
              type: string
              examples:
                - 5df263b7db5a7e6ea03fae9b
            created_at:
              description: The date and time the conversation was created
              type: string
              examples:
                - '2020-09-20T00:00:00+00:00'
            end_user_id:
              description: The ID of the end user associated with the conversation
              type: string
              examples:
                - 5f7e0e2c1e7c7e000f0f9c3a
            metadata:
              description: |
                A dictionary of key, value pairs assigned to the conversation
                - `metadata` keys may only be of type: `string`
                - `metadata` values may only be one of type: `string`, `boolean`, `integer`, or `number` (float)
              type: object
              examples:
                - pass: example_string_value
                  initial_url: https://example.com
                  locale: en-CA
              additionalProperties:
                type:
                  - string
                  - boolean
                  - integer
                  - number
                minimum: -9223372036854775808
                maximum: 9223372036854775807
            ai_agent_domain:
              description: The API domain of the AI Agent environment this webhook event is emitted from
              type: string
              examples:
                - acme.ada.support
                - acme.eu.ada.support
          examples:
            - conversation_id: 5df263b7db5a7e6ea03fae9b
              channel_id: 5df263b7db5a7e6ea03fae9b
              created_at: '2020-09-20T00:00:00+00:00'
              end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
              metadata:
                pass: example_string_value
                initial_url: https://example.com
                locale: en-CA
              ai_agent_domain: acme.ada.support
      examples:
        - type: v1.conversation.created
          timestamp: '2020-09-20T00:00:00+00:00'
          data:
            conversation_id: 5df263b7db5a7e6ea03fae9b
            channel_id: 5df263b7db5a7e6ea03fae9b
            created_at: '2020-09-20T00:00:00+00:00'
            end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
            metadata:
              pass: example_string_value
              initial_url: https://example.com
              locale: en-CA
            ai_agent_domain: acme.ada.support

    ConversationMessageWebhookPayload:
      properties:
        type:
          description: The webhook event type
          type:
            - string
          enum:
            - v1.conversation.message
          examples:
            - v1.conversation.message
        timestamp:
          description: >-
            The timestamp for when the event was generated, uses millisecond
            precision to help with event ordering needs
          type:
            - string
          examples:
            - '2020-09-20T00:00:00+00:00'
        data:
          type: object
          description: The webhook event data
          properties:
            message_id:
              description: The ID of the message that triggered the webhook event
              type:
                - string
              examples:
                - 61f46e0b-fa39-4e44-850b-c1ca8f958dd3
            conversation_id:
              description: The ID of the conversation that contains the message
              type:
                - string
              examples:
                - 5f7e0e2c1e7c7e000f0f9c3a
            end_user_id:
              description: The ID of the end user associated with the conversation
              type:
                - string
              examples:
                - 5f7e0e2c1e7c7e000f0f9c3a
            handoff_integration:
              description: >-
                The name of the handoff integration if the message is part of a handoff conversation.
                This field is null when the message is directed to the AI Agent.
              type:
                - string
                - 'null'
              examples:
                - null
                - zendesk_chat
                - zendesk_agent_workspace
                - salesforce
            channel:
              description: The channel that the message was sent on
              type: object
              allOf:
                - $ref: '#/components/schemas/ConversationMessageWebhookChannel'
            created_at:
              description: The date and time the message was created
              type:
                - string
              examples:
                - '2020-09-20T00:00:00+00:00'
            author:
              description: Information about the message author
              type: object
              properties:
                id:
                  type:
                    - string
                    - 'null'
                  description: >-
                    The ID of the user that will be participating in the
                    conversation
                  examples:
                    - 5df263b7db5a7e6ea03fae9b
                role:
                  description: The author's role
                  type: string
                  enum:
                    - end_user
                    - ai_agent
                    - human_agent
                  examples:
                    - end_user
                avatar:
                  description: The URL of the author's avatar
                  type:
                    - string
                    - "null"
                  examples:
                    - https://www.gravatar.com
                display_name:
                  description: The author's display name
                  type:
                    - string
                    - "null"
                  examples:
                    - Ada Lovelace
              examples:
                - id: 5df263b7db5a7e6ea03fae9b
                  role: end_user
                  avatar: https://www.gravatar.com
                  display_name: Ada Lovelace
            content:
              oneOf:
                - $ref: '#/components/schemas/TextContent'
                - $ref: '#/components/schemas/LinkContent'
                - $ref: '#/components/schemas/FileContent'
              discriminator:
                propertyName: type
                mapping:
                  text: '#/components/schemas/TextContent'
                  link: '#/components/schemas/LinkContent'
                  file: '#/components/schemas/FileContent'
              examples:
                - type: text
                  body: 'I need help with my order'
            ai_agent_domain:
              description: The API domain of the AI Agent environment this webhook event is emitted from
              type: string
              examples:
                - acme.ada.support
                - acme.eu.ada.support
          examples:
            - message_id: 61f46e0b-fa39-4e44-850b-c1ca8f958dd3
              conversation_id: 5f7e0e2c1e7c7e000f0f9c3a
              end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
              handoff_integration: null
              channel:
                id: 5f7e0e2c1e7c7e000f0f9c3a
                name: My Custom Channel
                description: A custom messaging channel for my AI Agent
                modality: messaging
                type: custom
                metadata:
                  example_key1: example_string_value
                  example_key2: true
                  example_key3: 123
                created_at: '2020-09-20T00:00:00+00:00'
              created_at: '2020-09-20T00:00:00+00:00'
              author:
                id: 5df263b7db5a7e6ea03fae9b
                role: end_user
                avatar: https://www.gravatar.com
                display_name: Ada Lovelace
              content:
                type: text
                body: 'I need help with my order'
              ai_agent_domain: acme.ada.support
      examples:
        - type: v1.conversation.message
          timestamp: '2020-09-20T00:00:00+00:00'
          data:
            message_id: 61f46e0b-fa39-4e44-850b-c1ca8f958dd3
            conversation_id: 5f7e0e2c1e7c7e000f0f9c3a
            end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
            handoff_integration: null
            channel:
              id: 5f7e0e2c1e7c7e000f0f9c3a
              name: My Custom Channel
              description: A custom messaging channel for my AI Agent
              modality: messaging
              type: custom
              metadata:
                example_key1: example_string_value
                example_key2: true
                example_key3: 123
              created_at: '2020-09-20T00:00:00+00:00'
            created_at: '2020-09-20T00:00:00+00:00'
            author:
              id: 5df263b7db5a7e6ea03fae9b
              role: end_user
              avatar: https://www.gravatar.com
              display_name: Ada Lovelace
            content:
              type: text
              body: 'I need help with my order'
            ai_agent_domain: acme.ada.support

    ConversationMessageWebhookNativeChannel:
      allOf:
        - $ref: '#/components/schemas/BaseChannel'
        - type: object
          properties:
            id:
              <<: *channel-id-field
              readOnly: false
            type:
              <<: *channel-type-field
              enum:
                - native
              readOnly: false
          required:
            - id
            - type

    ConversationMessageWebhookCustomChannel:
      allOf:
        - $ref: '#/components/schemas/BaseChannel'
        - type: object
          properties:
            id:
              <<: *channel-id-field
              format: id
              readOnly: false
            type:
              <<: *channel-type-field
              enum:
                - custom
              readOnly: false
            metadata:
              description: |
                A dictionary of key/value pairs assigned to the channel. Metadata may not exceed 4KB total
                - keys: string
                - values: string, boolean, or integer
              type: object
              additionalProperties:
                type:
                  - string
                  - boolean
                  - integer
                minimum: -9223372036854775808
                maximum: 9223372036854775807
            created_at:
              description: The date and time the channel was created
              type: string
              format: date-time
              readOnly: false
          required:
            - id
            - type

    ConversationMessageWebhookChannel:
      oneOf:
        - $ref: '#/components/schemas/ConversationMessageWebhookNativeChannel'
        - $ref: '#/components/schemas/ConversationMessageWebhookCustomChannel'
      discriminator:
        propertyName: type
        mapping:
          native: '#/components/schemas/ConversationMessageWebhookNativeChannel'
          custom: '#/components/schemas/ConversationMessageWebhookCustomChannel'

    ConversationEndedWebhookPayload:
      properties:
        type:
          description: The webhook event type
          type: string
          readOnly: false
          enum:
            - v1.conversation.ended
          examples:
            - v1.conversation.ended
        timestamp:
          description: >-
            The timestamp for when the event was generated, uses millisecond
            precision to help with event ordering
          type: string
          examples:
            - '2020-09-20T00:00:00+00:00'
        data:
          description: The webhook event data
          type: object
          properties:
            conversation_id:
              description: The ID of the conversation that was ended
              type: string
              examples:
                - 5df263b7db5a7e6ea03fae9b
            channel_id:
              description: The ID of the channel
              type: string
              examples:
                - 5df263b7db5a7e6ea03fae9b
            end_user_id:
              description: The ID of the end user associated with the conversation
              type: string
              examples:
                - 5f7e0e2c1e7c7e000f0f9c3a
            created_at:
              description: The date and time the conversation was created
              type: string
              examples:
                - '2020-09-20T00:00:00+00:00'
            updated_at:
              description: The date and time the conversation was last updated
              type: string
              examples:
                - '2020-09-20T00:00:00+00:00'
            ended_by:
              type: object
              properties:
                id:
                  type:
                    - string
                    - 'null'
                  description: The ID of the user that ended the conversation
                  examples:
                    - 5df263b7db5a7e6ea03fae9b
                role:
                  type: string
                  description: The role that ended the conversation
                  examples:
                    - end_user
                  enum:
                    - end_user
                    - system
                    - human_agent
            metadata:
              description: |
                A dictionary of key, value pairs assigned to the conversation
                - `metadata` keys may only be of type: `string`
                - `metadata` values may only be one of type: `string`, `boolean`, `integer`, or `number` (float)
              type: object
              examples:
                - pass: example_string_value
                  initial_url: https://example.com
                  locale: en-CA
              additionalProperties:
                type:
                  - string
                  - boolean
                  - integer
                  - number
                minimum: -9223372036854775808
                maximum: 9223372036854775807
            ai_agent_domain:
              description: The API domain of the AI Agent environment this webhook event is emitted from
              type: string
              examples:
                - acme.ada.support
                - acme.eu.ada.support
          examples:
            - conversation_id: 5df263b7db5a7e6ea03fae9b
              channel_id: 5df263b7db5a7e6ea03fae9b
              end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
              created_at: '2020-09-20T00:00:00+00:00'
              updated_at: '2020-09-20T00:00:00+00:00'
              ended_by:
                id: 5df263b7db5a7e6ea03fae9b
                role: end_user
              metadata:
                pass: example_string_value
                initial_url: https://example.com
                locale: en-CA
              ai_agent_domain: acme.ada.support
      examples:
        - type: v1.conversation.ended
          timestamp: '2020-09-20T00:00:00+00:00'
          data:
            conversation_id: 5df263b7db5a7e6ea03fae9b
            channel_id: 5df263b7db5a7e6ea03fae9b
            end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
            created_at: '2020-09-20T00:00:00+00:00'
            updated_at: '2020-09-20T00:00:00+00:00'
            ended_by:
              id: 5df263b7db5a7e6ea03fae9b
              role: end_user
            metadata:
              pass: example_string_value
              initial_url: https://example.com
              locale: en-CA
            ai_agent_domain: acme.ada.support

    ConversationHandoffEndedWebhookPayload:
      type: object
      properties:
        type:
          description: The webhook event type
          type: string
          readOnly: false
          enum:
            - v1.conversation.handoff.ended
          examples:
            - v1.conversation.handoff.ended
        timestamp:
          description: >-
            The timestamp for when the event was generated, uses millisecond
            precision to help with event ordering
          type: string
          examples:
            - '2020-09-20T00:00:00+00:00'
        data:
          description: The webhook event data
          type: object
          properties:
            conversation_id:
              description: The ID of the conversation where the handoff was ended
              type: string
              examples:
                - 5df263b7db5a7e6ea03fae9b
            end_user_id:
              description: The ID of the end user associated with the conversation
              type: string
              examples:
                - 5f7e0e2c1e7c7e000f0f9c3a
            handoff_integration:
              description: The handoff integration that was ended
              type: string
              examples:
                - custom-handoff
            ai_agent_domain:
              description: The API domain of the AI Agent environment this webhook event is emitted from
              type: string
              examples:
                - acme.ada.support
                - acme.eu.ada.support
          required:
            - conversation_id
            - end_user_id
            - handoff_integration
            - ai_agent_domain
          examples:
            - conversation_id: 5df263b7db5a7e6ea03fae9b
              end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
              handoff_integration: custom-handoff
              ai_agent_domain: acme.ada.support
      examples:
        - type: v1.conversation.handoff.ended
          timestamp: '2020-09-20T00:00:00+00:00'
          data:
            conversation_id: 5df263b7db5a7e6ea03fae9b
            end_user_id: 5f7e0e2c1e7c7e000f0f9c3a
            handoff_integration: custom-handoff
            ai_agent_domain: acme.ada.support

    ArticleLocale:
      description: The IETF BCP 47 language code for the article, defaults to `en` or to the value of language if provided
      type: string
      examples:
        - en-CA
        - en-GB
        - en
        - fr-CA
        - fr-FR

    DataApiConversation:
      type: object
      properties:
        _id:
          type: string
          description: Unique ID for the conversation record
          examples:
            - 5d8a7d080afd19b55945c8ab
        agent_id:
          description: The list of unique IDs for agents involved in the conversation
          examples:
            - - 619d95c0c063a5bf2b1efb7c
          items:
            type: string
          type: array
        agent_name:
          description: A list of names of the agents involved the conversation, corresponding to the agent IDs
          examples:
            - - Ada Lovelace
          items:
            type: string
          type: array
        agent_handle_time:
          type: number
          description: Time taken for a human agent to handle a conversation in seconds
          examples:
            - 4
        automated_resolution_classification:
          description: Classification of either Resolved or Not Resolved for the conversation
          examples:
            - Resolved
          type: string
        automated_resolution_classification_reason:
          description: Explanation of the reason for the assigned automated_resolution_classification
          examples:
            - The bot provided a detailed step-by-step guide on how to disable auto deposits, both on the mobile app and the web version.
          type: string
        bot_handle_time:
          type: number
          description: Time taken for the AI agent to handle a conversation in seconds
          examples:
            - 4
        browser:
          description: The browser used by the chatter
          examples:
            - chrome
          type: string
        browser_version:
          description: The version of the browser used by the chatter
          examples:
            - 95.0.4638.69
          type: string
        chatter_id:
          type: string
          description: The ID of the chatter having this conversation
          examples:
            - 5dbaef7283d791f585563d84
        csat:
          type: object
          description: Object of customer satisfaction survey data for this conversation
          examples:
            - comment: null
              feedback: null
              is_positive: false
              resolved: null
              score: 3
              style: EMOJI
              survey_type: end_chat
        date_created:
          type: string
          format: date-time
          description: Date and time the record was created (UTC)
          examples:
            - "2019-10-31T14:28:02"
        date_updated:
          type: string
          format: date-time
          description: Last date and time the record was updated (UTC)
          examples:
            - "2019-10-31T14:28:02"
        device:
          description: The device the chatter used, such as iphone, android, etc.
          examples:
            - macos
          type: string
        end_user_id:
          description: The ID of the end user used to identify the chatter profile in the conversation
          examples:
            - 619d95c0c063a5bf2b1efb64e
          type:
            - string
            - 'null'
        generated_topic_id:
          description: The unique ID associated with the generated conversation topic
          examples:
            - 654952d3e90767ff49713fbf
          type: string
        generated_topic_label:
          description: The title of the generated conversation topic
          examples:
            - Billing Inquiries
          type:
            - string
            - 'null'
        generated_topic_v2_id:
          description: The unique ID associated with the generated conversation topic using Topics V2
          examples:
            - 654952d3e90767ff49713fb1
          type:
            - string
            - 'null'
        generated_topic_v2_title:
          description: The title of the generated conversation topic using Topics V2
          examples:
            - Password Reset Inquiries
          type:
            - string
            - 'null'
        generated_topic_v2_desc:
          description: The descrtiption of the generated conversation topic using Topics V2
          examples:
            - All conversations regarding resetting passwords
          type:
            - string
            - 'null'
        generated_topic_v2_parent_id:
          description: The unique ID associated with the generated conversation topic's parent category topic. Null if topic has no parent category topic.
          examples:
            - 654952d3e90767ff49713fb2
          type:
            - string
            - 'null'
        inquiry_summary:
          description: An automatically generated summary of the customer's inquiry
          examples:
            - The customer wanted to know how to temporarily disable auto deposits.
          type: string
        is_engaged:
          type: boolean
          description: Whether the chatter engaged with the bot during this conversation
          examples:
            - true
        is_escalated:
          type: boolean
          description: Whether the chatter escalated to a live agent during this conversation
          examples:
            - false
        is_test_user:
          description: Whether the conversation was started by a test user
          examples:
            - false
          type: boolean
        language:
          description: The language the chatter used
          examples:
            - en
          type: string
        metavariables:
          type: object
          description: Object of metavariables and their values active during this conversations
          examples:
            - browser: chrome
              language: en
        oauth_channel:
          description: The channel used by Oauth
          examples:
            - sms
          type: string
        platform:
          description: Ada platform through which this conversation occurred
          examples:
            - chat
          type: string
        record_last_updated:
          type:
            - string
            - 'null'
          format: date-time
          description: Date and time the record was uploaded to the API
          examples:
            - "2019-10-31T14:28:02.865000+00:00"
        variables:
          type: object
          description: Object of global and auto_capture variables and their values last active during this conversations
          examples:
            - account_number: "1234"

    DataApiConversationsResponse:
      type: object
      properties:
        items:
          description: Records returned from the query
          type: array
          items:
            $ref: '#/components/schemas/DataApiConversation'
          examples:
            - _id: 5d8a7d080afd19b55945c8ab
              agent_id:
                - 619d95c0c063a5bf2b1efb7c
              agent_name:
                - Ada Lovelace
              agent_handle_time: 4
              automated_resolution_classification: Resolved
              automated_resolution_classification_reason: The bot provided a detailed step-by-step guide on how to disable auto deposits
              bot_handle_time: 4
              browser: chrome
              browser_version: 95.0.4638.69
              chatter_id: 5dbaef7283d791f585563d84
              csat:
                comment: null
                feedback: null
                is_positive: false
                resolved: null
                score: 3
                style: EMOJI
                survey_type: end_chat
              date_created: "2019-10-31T14:28:02"
              date_updated: "2019-10-31T14:29:02"
              device: macos
              end_user_id: 619d95c0c063a5bf2b1efb64e
              generated_topic_id: 654952d3e90767ff49713fbf
              generated_topic_label: Billing Inquiries
              generated_topic_v2_id: 654952d3e90767ff49713fb1
              generated_topic_v2_title: Password Reset Inquiries
              generated_topic_v2_desc: All conversations regarding resetting passwords
              generated_topic_v2_parent_id: 654952d3e90767ff49713fb2
              inquiry_summary: The customer wanted to know how to temporarily disable auto deposits
              is_engaged: true
              is_escalated: false
              is_test_user: false
              language: en
              metavariables:
                browser: chrome
                language: en
              oauth_channel: sms
              platform: chat
              record_last_updated: null
              variables:
                account_number: "1234"
        meta:
          type: object
          properties:
            next_page_uri:
              type:
                - string
                - 'null'
              description: Link to the next page of results matching the query
              examples:
                - https://example.ada.support/api/v2/export/conversations?created_since=2023-07-08T06%3A01%3A39%2B00%3A00&created_to=2023-07-22T00%3A00%3A00%2B00%3A00
          examples:
            - next_page_uri: https://example.ada.support/api/v2/export/conversations?created_since=2023-07-08T06%3A01%3A39%2B00%3A00&created_to=2023-07-22T00%3A00%3A00%2B00%3A00

    DataApiMessage:
      type: object
      properties:
        _id:
          type: string
          description: Unique ID for the message record
          examples:
            - 5d8a7d080afd19b55945c8ab
        answer_id:
          type:
            - string
            - 'null'
          description: Internal ID of the answer (response) that triggered this message. Null if the message was not sent by a bot, and None if it was sent by a generative bot.
          examples:
            - 6392e0f865ba38041ddd5966
        answer_title:
          type:
            - string
            - 'null'
          description: Title of the answer (response) that triggered this message. Null if the message was not sent by a bot, or if it was sent by a generative bot.
          examples:
            - Greeting
        chatter_id:
          type:
            - string
            - 'null'
          description: Internal ID of the chatter who sent this message. Corresponds to the `_id` field of Chatter objects.
          examples:
            - 6009dd3c81dfae3a4e990acb
        conversation_id:
          type: string
          description: Internal ID of the conversation in which this message was sent. Corresponds to the `_id` field of Conversation objects.
          examples:
            - 5dba43ebedb828146bc871b6
        date_created:
          type: string
          format: date-time
          description: Time the record was created (UTC)
          examples:
            - "2019-10-31T14:28:02.865000+00:00"
        link_was_clicked:
          type:
            - boolean
            - 'null'
          description: Indicates if the link in the answer (response) was clicked
          examples:
            - false
        message_data:
          type: object
          description: Data associated with this message
          examples:
            - _type: greeting
              external_chat_id: <uuid_v4_id>
              reviewable_message: false
        recipient:
          type: string
          description: Recipient of this message
          examples:
            - ada
        record_last_updated:
          type: string
          format: date-time
          description: Date and time the record was uploaded to the API (UTC)
          examples:
            - "2019-10-31T14:28:02.865000+00:00"
        review:
          type: integer
          format: int32
          description: Rating given to this answer by the chatter
          minimum: 0
          maximum: 5
          examples:
            - 0
        sender:
          type: string
          description: Sender of this message
          examples:
            - b9e51eae-5449-4a46-b6ce-aef2dcb4e067
        in_response_to:
          description: Internal ID of the message that this message is in response to. None if the message is not in response to another message.
          type: string
          examples:
            - 6392e0f865ba38041ddd5966

    DataApiMessagesResponse:
      type: object
      properties:
        items:
          description: Records returned from the query
          type: array
          items:
            $ref: '#/components/schemas/DataApiMessage'
          examples:
            - _id: 5d8a7d080afd19b55945c8ab
              answer_id: 6392e0f865ba38041ddd5966
              answer_title: Greeting
              chatter_id: 6009dd3c81dfae3a4e990acb
              conversation_id: 5dba43ebedb828146bc871b6
              date_created: "2019-10-31T14:28:02.865000+00:00"
              link_was_clicked: false
              message_data:
                _type: greeting
                external_chat_id: <uuid_v4_id>
                reviewable_message: false
              recipient: ada
              record_last_updated: "2019-10-31T14:28:02.865000+00:00"
              review: 0
              sender: b9e51eae-5449-4a46-b6ce-aef2dcb4e067
              in_response_to: 6392e0f865ba38041ddd5966
        meta:
          type: object
          properties:
            next_page_uri:
              type:
                - string
                - 'null'
              description: Link to the next page of results matching the query
              examples:
                - https://example.ada.support/api/v2/export/messages?created_since=2023-07-01T14%3A01%3A16.257000%2B00%3A00&created_to=2023-07-22T00%3A00%3A00%2B00%3A00
          examples:
            - next_page_uri: https://example.ada.support/api/v2/export/messages?created_since=2023-07-01T14%3A01%3A16.257000%2B00%3A00&created_to=2023-07-22T00%3A00%3A00%2B00%3A00
  parameters:
    CursorParam:
      in: query
      name: cursor
      description: >-
        The ID that marks the start or beginning of the returned records
      schema:
        type: string
        format: id
        examples:
          - '5f7e0e2c1e7c7e000f0f9c3a'
      required: false
    LimitParam:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 100
        examples:
          - 10
      required: false
      description: The number of records to return
  examples:
    AuthorizationError:
      value:
        errors:
        - type: authorization_error
          message: You are not authorized to access this resource
          details: You are not authorized to access this resource
    BadRequestError:
      value:
        errors:
        - type: bad_request
          message: Invalid request
          details: '{''profile'': {''system_properties'': [''Unknown field.'']}}'
    DuplicateResourceError:
      value:
        errors:
        - type: duplicate_resource
          message: Duplicate resource
          details: A resource with the same id already exists.
    NotFoundError:
      value:
        errors:
        - type: resource_not_found
          message: Resource not found
          details: The requested resource with id 5f7e0e2c1e7c7e000f0f9c3a was not
            found
    ClientNotFoundError:
      value:
        errors:
        - type: resource_not_found
          message: Sorry, no client 'client_name' exists
          details: null
    UnauthorizedError:
      value:
        errors:
        - type: unauthorized
          message: You are not authorized to access this resource
          details: You are not authorized to access this resource
    ContentTooLargeError:
      value:
        errors:
        - type: content_too_large
          message: Content too large
          details: 'Maximum request size of 4.0 MB exceeded. Content length: 5.0 MB'
    UnprocessableContentError:
      value:
        errors:
        - type: unprocessable_content
          message: Unprocessable content
          details: The request was well-formed but was unable to be followed due to
            semantic errors
    TooManyRequestsError:
      value:
        errors:
        - type: rate_limit_exceeded
          message: Rate limit exceeded
          details: 50 requests allowed per second
    InternalServerError:
      value:
        errors:
        - type: internal_server_error
          message: An unknown error occurred
          details: 'An unknown error occurred. error_id: 91d435a7-e0b4-4c56-a097-8907e9ed851e'

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      
webhooks:
  v1.conversation.created:
    post:
      operationId: conversationCreatedWebhook
      tags:
        - Conversation Webhooks
      summary: 'Webhook: Conversation created'
      description: A webhook sent when a conversation is created
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreatedWebhookPayload'
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully

  v1.conversation.message:
    post:
      operationId: conversationMessageWebhook
      tags:
        - Conversation Webhooks
      summary: 'Webhook: Conversation message'
      description: A webhook sent when a message is sent to a conversation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationMessageWebhookPayload'
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully

  v1.conversation.ended:
    post:
      operationId: conversationEndedWebhook
      tags:
        - Conversation Webhooks
      summary: 'Webhook: Conversation ended'
      description: A webhook sent when a conversation ends
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationEndedWebhookPayload'
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully

  v1.conversation.handoff.ended:
    post:
      operationId: conversationHandoffEndedWebhook
      tags:
        - Conversation Webhooks
      summary: 'Webhook: Conversation handoff ended'
      description: A webhook sent when a handoff is ended
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationHandoffEndedWebhookPayload'
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully

  v1.end_user.created:
    post:
      operationId: endUserCreatedWebhook
      tags:
      - End User Webhooks
      summary: 'Webhook: End user created'
      description: A webhook sent when a new end user is created
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserCreatedWebhookPayload'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received
            successfully
  v1.end_user.updated:
    post:
      operationId: endUserUpdatedWebhook
      tags:
      - End User Webhooks
      summary: 'Webhook: End user updated'
      description: A webhook sent when an end user is updated
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserUpdatedWebhookPayload'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received
            successfully
servers:
- url: https://{handle}.ada.support/api/
  variables:
    handle:
      default: example
      description: The subdomain of the client