openapi: 3.1.0
info:
  title: Knowledge
  version: 1.0.0
paths:
  /v2/knowledge/sources/:
    get:
      operationId: list
      summary: Get knowledge sources
      description: Get knowledge sources
      tags:
        - knowledge > sources
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Knowledge sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_sources_list_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: create
      summary: Create a knowledge source
      description: Create a knowledge source
      tags:
        - knowledge > sources
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: Duplicate Resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeSourceCreateRequest'
  /v2/knowledge/sources/{id}:
    delete:
      operationId: delete
      summary: Delete a knowledge source
      description: >
        Delete a knowledge source, and its related articles


        Deletion is asynchronous: a `204` response means the deletion request was accepted and is processed in the
        background. While deletion is in progress, the source reports a `status` of `deleting`; if deletion fails, the
        source reports `delete_failed`, and you can re-issue the request to retry. To confirm completion, re-query the
        knowledge source list until the source no longer appears. A `404` is still returned when the knowledge source
        does not exist.
      tags:
        - knowledge > sources
      parameters:
        - name: id
          in: path
          description: id of the knowledge source to delete
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Knowledge source deletion accepted; the source and its related articles are deleted in the background
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_sources_delete_Response_204'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      operationId: update
      summary: Update a knowledge source
      description: Update a knowledge source
      tags:
        - knowledge > sources
      parameters:
        - name: id
          in: path
          description: id of the knowledge source to update
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeSourceUpdateRequest'
  /v2/knowledge/articles/:
    get:
      operationId: list
      summary: Get knowledge articles
      description: Get knowledge articles
      tags:
        - knowledge > articles
      parameters:
        - name: cursor
          in: query
          description: The article cursor that marks the start or beginning of the returned article records
          required: false
          schema:
            type: string
            format: id
        - name: limit
          in: query
          description: The number of article records to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: id
          in: query
          description: Filter by article id
          required: false
          schema:
            type: array
            items:
              type: string
              format: id
        - name: enabled
          in: query
          description: Filter by enabled status
          required: false
          schema:
            type: array
            items:
              type: boolean
        - name: language
          in: query
          description: Filter by language
          required: false
          schema:
            type: array
            items:
              type: string
        - name: knowledge_source_id
          in: query
          description: Filter by knowledge source
          required: false
          schema:
            type: array
            items:
              type: string
              format: id
        - name: tag_ids
          in: query
          description: Filter by tag ids
          required: false
          schema:
            type: array
            items:
              type: string
              format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Matching knowledge articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_articles_list_Response_200'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      operationId: delete
      summary: Delete multiple articles
      description: >
        Delete multiple articles


        Deletion is asynchronous: a `204` response means the deletion request was accepted and the matching articles are
        deleted in the background. To confirm completion, re-query `GET /v2/knowledge/articles/` with the same filters
        until no articles match. A `404` is still returned when no articles match the provided filters.
      tags:
        - knowledge > articles
      parameters:
        - name: id
          in: query
          description: Filter by article id
          required: false
          schema:
            type: array
            items:
              type: string
              format: id
        - name: enabled
          in: query
          description: Filter by enabled status
          required: false
          schema:
            type: array
            items:
              type: boolean
        - name: language
          in: query
          description: Filter by language
          required: false
          schema:
            type: array
            items:
              type: string
        - name: knowledge_source_id
          in: query
          description: Filter by knowledge source
          required: false
          schema:
            type: array
            items:
              type: string
              format: id
        - name: tag_ids
          in: query
          description: Filter by tag ids
          required: false
          schema:
            type: array
            items:
              type: string
              format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Article deletion accepted; matching articles are deleted in the background
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_articles_delete_Response_204'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/knowledge/articles/{id}:
    get:
      operationId: get
      summary: Get a single knowledge article
      description: Get knowledge article by id
      tags:
        - knowledge > articles
      parameters:
        - name: id
          in: path
          description: The id of the article to retrieve
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Knowledge article
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeArticleResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      operationId: delete-by-id
      summary: Delete a single article
      description: Delete an article
      tags:
        - knowledge > articles
      parameters:
        - name: id
          in: path
          description: The id of the article to delete
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Articles successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_articles_deleteById_Response_204'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/knowledge/bulk/articles/:
    post:
      operationId: bulk-upsert
      summary: Upsert multiple articles
      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 by default. Higher limits are available for eligible plans — contact
        your Ada team.


        **Behavior at the article limit:**

        Requests that only update existing articles (every `id` in the request already exists) continue to succeed even
        when your knowledge base is at its article limit. A request that introduces any new article `id` while at the
        limit is rejected as a whole with a `400` response. The error message is `Maximum article limit of {N}
        exceeded`, where `{N}` is your article limit, and the error details include a `code` of
        `knowledge.articles.total_exceeded`, the list of `new_article_ids` that triggered the rejection (capped at the
        first 100), and the total `new_article_count`. Use these fields to separate new articles from update-only
        batches, which can still be submitted.
      tags:
        - knowledge > articles
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/KnowledgeArticleUpsertRequest'
  /v2/knowledge/tags/:
    get:
      operationId: list
      summary: Get article tags
      description: Get article tags
      tags:
        - knowledge > tags
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Article tags
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_tags_list_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/knowledge/tags/{id}:
    delete:
      operationId: delete
      summary: Delete a single article tag
      description: Delete an article tag
      tags:
        - knowledge > tags
      parameters:
        - name: id
          in: path
          description: The id of the article tag to delete
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Article tag deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/knowledge_tags_delete_Response_204'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/knowledge/bulk/tags/:
    post:
      operationId: upsert-multiple
      summary: Upsert multiple tags
      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.
      tags:
        - knowledge > tags
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ArticleTag'
  /v2/end-users/{end_user_id}:
    get:
      operationId: get-end-user-by-id
      summary: Get an end user
      description: Get a specific end user by id
      tags:
        - endUsers
      parameters:
        - name: end_user_id
          in: path
          description: The Ada end_user_id
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          description: Invalid 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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      operationId: patch-end-user-by-id
      summary: Update an end user
      description: Update a specific end user by id
      tags:
        - endUsers
      parameters:
        - name: end_user_id
          in: path
          description: The Ada end_user_id
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndUser'
        '400':
          description: Invalid 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'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserRequest'
  /v2/end-users/:
    get:
      operationId: get-end-users
      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).
      tags:
        - endUsers
      parameters:
        - name: external_id
          in: query
          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).
          required: false
          schema:
            type: string
            maxLength: 36
        - name: cursor
          in: query
          description: The ID that marks the start or beginning of the returned records
          required: false
          schema:
            type: string
            format: id
        - name: limit
          in: query
          description: The number of records to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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:
                $ref: '#/components/schemas/End Users_getEndUsers_Response_200'
        '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 — no end user is mapped to the requested external_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: create-end-user
      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.
      tags:
        - endUsers
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '413':
          description: Content Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEndUserRequest'
  /v2/end-users/delete:
    post:
      operationId: submit-a-bulk-end-user-deletion-request
      summary: Submit a bulk end-user deletion request
      description: >-
        Submits a request to erase all personal data associated with the supplied identifiers. Replace `example` with
        your AI Agent's handle. A successful call returns a `202` with a `job_id` you can poll for status. Requests that
        set `client_reference` are idempotent for 24 hours: an identical resubmission within that window returns the
        original job instead of creating a new one. Requests that omit `client_reference` are not deduplicated.
        Separately, the erasure engine rejects an identifier submitted within the previous 7 days, and a single
        identifier in that cooldown can fail an entire job.
      tags:
        - submitDeletionRequest
      responses:
        '202':
          description: The deletion request was accepted and a job was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletionRequestAccepted'
        '400':
          description: Invalid request body, for example no identifiers.
          content:
            application/json:
              schema:
                description: Any type
        '401':
          description: Authentication token is missing or invalid. Try generating a new token.
          content:
            application/json:
              schema:
                description: Any type
        '403':
          description: The token is not authorized to perform this operation.
          content:
            application/json:
              schema:
                description: Any type
        '413':
          description: The request body exceeds the maximum size of 512 KB. Split the identifiers across multiple requests.
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: Too many requests. Retry after slowing the request rate.
          content:
            application/json:
              schema:
                description: Any type
        '500':
          description: Something went wrong on Ada's end.
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletionRequest'
  /v2/jobs/{job_id}:
    get:
      operationId: get-a-deletion-job
      summary: Get a deletion job
      description: >-
        Returns the current state of a deletion job, including the per-identifier dispositions. A job for an unknown or
        unowned `job_id` returns `404`.
      tags:
        - getDeletionJob
      parameters:
        - name: job_id
          in: path
          description: Identifier of the deletion job returned when the request was submitted.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The deletion job was found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletionJob'
        '401':
          description: Authentication token is missing or invalid. Try generating a new token.
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: No deletion job exists for the supplied `job_id` under this AI Agent.
          content:
            application/json:
              schema:
                description: Any type
        '429':
          description: Too many requests. Retry after slowing the request rate.
          content:
            application/json:
              schema:
                description: Any type
        '500':
          description: Something went wrong on Ada's end.
          content:
            application/json:
              schema:
                description: Any type
  /v2/platform-integrations/:
    get:
      operationId: get-platform-integrations
      summary: List integrations
      description: Get a list of platform integrations owned by your account (e.g. a developer sandbox)
      tags:
        - platformIntegrations
      parameters:
        - name: cursor
          in: query
          description: The ID that marks the start or beginning of the returned records
          required: false
          schema:
            type: string
            format: id
        - name: limit
          in: query
          description: The number of records to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Platform integrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Platform Integrations_getPlatformIntegrations_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: create-platform-integration
      summary: Create an integration
      description: Create an integration. Integrations are created in `development` status by default.
      tags:
        - platformIntegrations
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Platform integration created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Platform Integrations_createPlatformIntegration_Response_200'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformIntegrationCreateRequest'
  /v2/platform-integrations/{id}:
    patch:
      operationId: update-single-platform-integration
      summary: Update an integration
      description: >-
        Update a platform integration. **_Note:_ only integrations in development may be updated. Integrations submitted
        for publication cannot be updated.**
      tags:
        - platformIntegrations
      parameters:
        - name: id
          in: path
          description: The ID of the platform integration to update
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformIntegrationUpdateRequest'
  /v2/platform-integrations/{id}/installations/self:
    get:
      operationId: get-platform-integration-installation-self
      summary: Get an installation
      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.
      tags:
        - platformIntegrations
      parameters:
        - name: id
          in: path
          description: The ID of the platform integration to fetch installation for
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformIntegrationInstallation'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/platform-integrations/{platform_integration_id}/installations/{installation_id}:
    patch:
      operationId: update-platform-integration-installation
      summary: Update installation status
      description: Update status after installation. An installation can be `complete` or `incomplete`.
      tags:
        - platformIntegrations
      parameters:
        - name: platform_integration_id
          in: path
          description: The ID of the platform integration
          required: true
          schema:
            type: string
            format: id
        - name: installation_id
          in: path
          description: The ID of the installation to update
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformIntegrationInstallationUpdateRequest'
  /v2/analytics/audit-log/events/:
    get:
      operationId: list-audit-log-events
      summary: List Audit log events
      description: >-
        Retrieve the authenticated account's own Audit log events, newest first, in cursor-paginated pages. Intended for
        pulling the Audit log into a SIEM.


        Pagination is cursor-based: read `meta.next_page_url` and replay it verbatim to fetch the next page.
        `next_page_url` is `null` on the last or empty page. The time window and `cursor` must be held constant across
        pages; the recommended way to guarantee this is to replay the returned `next_page_url` unchanged.


        No field filters are exposed: callers pull the full time window and filter on their own side (the SIEM).


        Validation errors (missing or invalid `start_date` or `end_date`, a window wider than 30 days, a malformed
        cursor, or a window change mid-pagination) return `400`.


        Rate limits (per account): 10 requests per second, 120 per minute, and 40,000 per day. A `429` means a limit was
        exceeded; back off and retry. For ongoing ingestion, poll on a steady cadence (for example, every few minutes)
        rather than in a tight loop.


        Backfilling vs incremental pulls: a single request covers at most 30 days. To backfill more history, issue
        successive requests over adjacent windows of up to 30 days. For incremental pulls, set `start_date` to just
        after the newest `timestamp` you have already stored, then follow `next_page_url` until it is `null`.
      tags:
        - auditLog
      parameters:
        - name: start_date
          in: query
          description: Start of the time window (inclusive), ISO 8601. The window (`end_date - start_date`) may not exceed 30 days.
          required: true
          schema:
            type: string
            format: date-time
        - name: end_date
          in: query
          description: >-
            End of the time window (inclusive), ISO 8601. When omitted it defaults to the request time (UTC); the
            resolved value is reflected in `next_page_url`, so replay the returned `next_page_url` verbatim to keep the
            window fixed across pages.
          required: false
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          description: >-
            Maximum events per page. Out-of-range or non-integer values are rejected with `400`; the applied limit is
            not echoed in the response.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
        - name: cursor
          in: query
          description: >-
            Opaque base64-encoded pagination cursor from a previous response's `meta.next_page_url`. Treat it as an
            opaque token, not an id. The time window and `cursor` must be held constant across pages: replay the
            returned `next_page_url` unchanged.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A cursor-paginated page of Audit log events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogEventList'
        '400':
          description: Bad Request (validation, cursor, or window drift)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized (missing or non-Bearer token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found (Audit log API not enabled for this account)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests (rate limit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/channels/:
    get:
      operationId: get-channels
      summary: Get a list of channels
      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
      tags:
        - channels
      parameters:
        - name: limit
          in: query
          description: The number of records to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          description: The ID that marks the start or beginning of the returned records
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: The type of the channels to retrieve
          required: true
          schema:
            $ref: '#/components/schemas/V2ChannelsGetParametersType'
        - name: modality
          in: query
          description: The modality of the channels to retrieve
          required: false
          schema:
            $ref: '#/components/schemas/V2ChannelsGetParametersModality'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Channels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channels_getChannels_Response_200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: create-channel
      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.
      tags:
        - channels
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '413':
          description: Content Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomChannel'
  /v2/channels/{channel_id}:
    patch:
      operationId: update-channel
      summary: Update a channel
      description: Update a channel's capabilities. Only custom channels can be updated; native channels are read-only.
      tags:
        - channels
      parameters:
        - name: channel_id
          in: path
          description: The ID of the channel to update
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Channel updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomChannel'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChannel'
  /v2/conversations/email/:
    post:
      operationId: create-email-conversation
      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.
      tags:
        - conversations
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailConversationCreateRequest'
  /v2/conversations/:
    post:
      operationId: create-conversation
      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.
      tags:
        - conversations
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
  /v2/conversations/{conversation_id}/:
    get:
      operationId: get-conversation-by-id
      summary: Get a conversation
      description: Get a conversation by its ID
      tags:
        - conversations
      parameters:
        - name: conversation_id
          in: path
          description: The ID of the conversation to retrieve
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      operationId: patch-conversation-by-id
      summary: Update a conversation
      description: Update a conversation's metadata by its ID
      tags:
        - conversations
      parameters:
        - name: conversation_id
          in: path
          description: The ID of the conversation to update
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationPatchRequest'
  /v2/conversations/{conversation_id}/messages/:
    get:
      operationId: fetch-conversation-messages-by-id
      summary: Get conversation messages
      description: Get messages (paginated) for a conversation by its ID
      tags:
        - conversations
      parameters:
        - name: conversation_id
          in: path
          description: The ID of the conversation
          required: true
          schema:
            type: string
            format: id
        - name: cursor
          in: query
          description: Cursor for pagination. Use the value from `meta.next_page_url` in the previous response.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of messages to return (default 100, max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: create-message
      summary: Create a new message
      description: Create a new message in a conversation. The maximum request size is 10MB.
      tags:
        - conversations
      parameters:
        - name: conversation_id
          in: path
          description: The ID of the conversation
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreateRequest'
  /v2/conversations/{conversation_id}/end/:
    post:
      operationId: end-conversation
      summary: End a conversation
      description: Ends the conversation specified by the `conversation_id`
      tags:
        - conversations
      parameters:
        - name: conversation_id
          in: path
          description: The ID of the conversation to end
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Conversation ended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversations_endConversation_Response_200'
        '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'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/conversations/{conversation_id}/end-handoff/:
    post:
      operationId: end-handoff
      summary: End Handoff
      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.
      tags:
        - conversations
      parameters:
        - name: conversation_id
          in: path
          description: The ID of the conversation to end handoff for
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Handoff ended successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversations_endHandoff_Response_200'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Conversation is not in an active handoff state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/conversations/{conversation_id}/attachments/:
    post:
      operationId: upload-attachment
      summary: Upload a file attachment
      description: >
        Upload a temporary file attachment to a conversation. The file is stored on Ada-managed

        storage and a presigned URL is returned that is valid for up to 7 days. Use that URL to

        create a file message by calling the `/v2/conversations/{conversation_id}/messages/`

        endpoint with `content.type` set to `file`. The maximum file size is 50MB.


        This endpoint provides temporary media storage for use within a conversation. It is

        **not** equivalent to the native attachment experience in Ada's widget handoff

        integrations (for example, the paperclip in Zendesk Messaging). With native widget

        attachments, files are uploaded directly into your agent platform (such as Sunshine

        Conversations / Zendesk) and hosted there. That native path is only available to Ada's

        web channel and is not accessible through the Conversations API.


        If you are building a headless Conversations API integration and want to send an

        attachment from an end user to a human agent mid-conversation so that it appears natively

        in your agent platform, upload the file using your agent platform's own attachment

        endpoints (for example, the Sunshine Conversations Attachments API for Zendesk) and

        consult that platform's documentation.


        **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
      tags:
        - conversations
      parameters:
        - name: conversation_id
          in: path
          description: The ID of the conversation
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload (max 50MB)
              required:
                - file
  /v2/webhooks/:
    get:
      operationId: list-webhooks
      summary: List webhooks
      description: List all webhook subscriptions configured for this AI Agent
      tags:
        - webhookManagement
      parameters:
        - name: limit
          in: query
          description: Maximum number of webhooks to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          description: Cursor for pagination
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook Management_listWebhooks_Response_200'
        '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: create-webhook
      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
      tags:
        - webhookManagement
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: The URL that will receive webhook events
                description:
                  type: string
                  default: ''
                  description: A description of the webhook
                event_filters:
                  type: array
                  items:
                    type: string
                  description: Event types to subscribe to. An empty list subscribes to all events
                enabled:
                  type: boolean
                  default: true
                  description: Whether the webhook is enabled
              required:
                - url
  /v2/webhooks/{id}:
    get:
      operationId: get-webhook
      summary: Get a webhook
      description: Get the details of a specific webhook subscription
      tags:
        - webhookManagement
      parameters:
        - name: id
          in: path
          description: The webhook ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
    delete:
      operationId: delete-webhook
      summary: Delete a webhook
      description: Delete a webhook subscription
      tags:
        - webhookManagement
      parameters:
        - name: id
          in: path
          description: The webhook ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Webhook deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook Management_deleteWebhook_Response_204'
        '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: update-webhook
      summary: Update a webhook
      description: Update a webhook subscription. Only the fields provided in the request body will be updated
      tags:
        - webhookManagement
      parameters:
        - name: id
          in: path
          description: The webhook ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      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'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: The URL that will receive webhook events
                description:
                  type: string
                  description: A description of the webhook
                event_filters:
                  type: array
                  items:
                    type: string
                  description: Event types to subscribe to. An empty list subscribes to all events
                enabled:
                  type: boolean
                  description: Whether the webhook is enabled
  /v2/webhooks/{id}/secret/:
    get:
      operationId: get-webhook-secret
      summary: Get webhook signing secret
      description: Get the signing secret for a webhook. Use this secret to verify that incoming webhook payloads are authentic
      tags:
        - webhookManagement
      parameters:
        - name: id
          in: path
          description: The webhook ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook signing secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook Management_getWebhookSecret_Response_200'
        '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: rotate-webhook-secret
      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
      tags:
        - webhookManagement
      parameters:
        - name: id
          in: path
          description: The webhook ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Signing secret rotated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook Management_rotateWebhookSecret_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                  description: An optional custom signing key. If not provided, a new key is generated automatically
  /v2/webhooks/event-types/:
    get:
      operationId: list-webhook-event-types
      summary: List webhook event types
      description: List all available event types that webhooks can subscribe to
      tags:
        - webhookManagement
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of event types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook Management_listWebhookEventTypes_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/persona/:
    get:
      operationId: get-persona
      summary: Get persona
      description: Retrieve the current persona configuration.
      tags:
        - persona
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      operationId: update-persona
      summary: Update persona
      description: >-
        Partially update the persona configuration. Only the fields provided in the request body are updated; omitted
        fields retain their existing values. Fields that are not part of the public persona schema are rejected.
      tags:
        - persona
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonaUpdate'
  /v2/variables/:
    get:
      operationId: list
      summary: List Variables
      description: |
        Returns the Variables accessible to the AI Agent (the Variables shown
        on the dashboard). Note: Reserved and internal Variables are not included.
      tags:
        - Variables
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of Variables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/variables_list_Response_200'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/variables/{id}:
    get:
      operationId: get
      summary: Get a Variable
      description: |
        Returns a single accessible Variable by id. An id that is unknown,
        malformed, or refers to a reserved or internal Variable returns `404`.
      tags:
        - Variables
      parameters:
        - name: id
          in: path
          description: The id of the Variable to retrieve
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The Variable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariableSummary'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/custom-instructions/:
    get:
      operationId: list-custom-instructions
      summary: List custom instructions
      description: >-
        Retrieve the AI Agent's custom instructions, live and inactive, in cursor-paginated pages ordered by id.


        Pagination is cursor-based: read `meta.next_page_url` and replay it verbatim to fetch the next page.
        `next_page_url` is `null` on the last or empty page.
      tags:
        - customInstructions
      parameters:
        - name: cursor
          in: query
          description: >-
            The id that marks the start of the returned records. Use the value from `meta.next_page_url` in the previous
            response.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: The number of records to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomInstructionList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: create-custom-instruction
      summary: Create a custom instruction
      description: >-
        Create a new custom instruction for the AI Agent. New instructions default to inactive (`enabled: false`);
        enable one by setting `enabled: true` on create or via a later update.
      tags:
        - customInstructions
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomInstruction'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: >-
            Conflict — the title is already used by another custom instruction, or enabling would exceed the AI Agent's
            enabled-instruction limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomInstructionCreate'
  /v2/custom-instructions/{custom_instruction_id}:
    get:
      operationId: get-custom-instruction-by-id
      summary: Get a custom instruction
      description: Retrieve a single custom instruction by its id
      tags:
        - customInstructions
      parameters:
        - name: custom_instruction_id
          in: path
          description: The id of the custom instruction
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomInstruction'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      operationId: delete-custom-instruction
      summary: Delete a custom instruction
      description: Delete a custom instruction by its id
      tags:
        - customInstructions
      parameters:
        - name: custom_instruction_id
          in: path
          description: The id of the custom instruction
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Custom Instructions_deleteCustomInstruction_Response_204'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      operationId: update-custom-instruction
      summary: Update a custom instruction
      description: >-
        Update a custom instruction. Only the fields provided in the request body are changed; omitted fields are left
        as they are.
      tags:
        - customInstructions
      parameters:
        - name: custom_instruction_id
          in: path
          description: The id of the custom instruction
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomInstruction'
        '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'
        '409':
          description: >-
            Conflict — the new title is already used by another custom instruction, or enabling would exceed the AI
            Agent's enabled-instruction limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomInstructionUpdate'
  /v2/tools/:
    get:
      operationId: list
      summary: List tools
      description: |
        Returns the AI Agent's tools in a single inventory, cursor-paginated, in
        fixed source order: `api`, then `code`. Each source is ordered by id.
        Replay `meta.next_page_url` verbatim to fetch the next page;
        `next_page_url` is `null` on the last or empty page.

        Each item is the same `Tool` envelope as `GET /v2/tools/{tool_id}`,
        without the type body (`api` / `code`). HTTP details and source code
        belong on a single-tool fetch.

        `type` skips the excluded sources entirely rather than filtering after
        the query. `enabled` filters on the tool's own `enabled` flag — the
        same field returned on each item — for every type.

        A cursor is bound to the Agent that minted it and to the `type` /
        `enabled` filters in effect. Changing those filters, or presenting
        another Agent's cursor, returns `400`.
      tags:
        - Tools
      parameters:
        - name: type
          in: query
          description: Restrict the list to one tool type. Omitted sources are not queried.
          required: false
          schema:
            $ref: '#/components/schemas/V2ToolsGetParametersType'
        - name: enabled
          in: query
          description: |
            Filter on the tool's own `enabled` flag. Same meaning for `api`
            and `code`: the stored per-tool toggle.
          required: false
          schema:
            type: boolean
        - name: limit
          in: query
          description: Maximum tools per page. Default 25. Out-of-range values return `400`.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: cursor
          in: query
          description: |
            Opaque pagination cursor from a previous response's
            `meta.next_page_url`. Treat it as an opaque token, not an id.
            Replay the returned `next_page_url` unchanged.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A page of tools
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolList'
        '400':
          description: Bad Request — invalid query parameter or cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      operationId: create
      summary: Create a tool
      description: |
        Creates an `api` or `code` tool.

        The body is the `Tool` envelope without `id` or read-only fields
        (`inputs[].required`). Request `body` / `headers` and code
        `environment` are optional. `availability` is the structured
        Knowledge rule object, never the internal DSL string.
        `Authorization` headers on `api` tools are stored but stripped
        on every read. A `code.environment` row with
        `source=sensitive_value` is write-only: create stores the
        submitted value (empty means an empty secret). A GET-then-POST
        clone does not copy the stored secret. Send it again.
      tags:
        - Tools
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '201':
          description: The created tool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: >-
            Conflict — the name collides with a tool of the other type (api↔code). Same-type api name reuse is not
            rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable — illegal write for this type, or the body failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolCreate'
  /v2/tools/{tool_id}:
    get:
      operationId: get
      summary: Get a tool by ID
      description: |
        Returns a single tool in the unified `Tool` shape, whatever its type.
        The contract the model sees (`name`, `description`, `inputs`,
        `outputs`) and the controls that gate it (`enabled`, `direct_use`,
        `availability`) sit at the top level; everything specific to how the
        tool runs is nested under the key matching `type`.

        `Authorization` headers are stripped from `api.request.headers`; other
        header values pass through with variable references translated to the
        `{var:<name>|<default>}` form.
      tags:
        - Tools
      parameters:
        - name: tool_id
          in: path
          description: The tool's id
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The tool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '400':
          description: Bad Request — the path is not a well-formed id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Tool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      operationId: delete
      summary: Delete a tool
      description: |
        Soft-deletes an `api` or `code` tool. An `api` tool that other
        entities still reference returns `409`. Code tools have no
        dependency check.
      tags:
        - Tools
      parameters:
        - name: tool_id
          in: path
          description: The tool's id
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The tool was deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tools_delete_Response_204'
        '400':
          description: Bad Request — the path is not a well-formed id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Tool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: >-
            Conflict — an api tool is referenced by other entities, and dependency-surfacing is on. Not returned for
            code tools.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable — this tool type cannot be deleted here
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      operationId: update
      summary: Update a tool
      description: |
        Partially update a tool. Omitted fields are preserved.

        Nested objects (`api`, `code`, `api.request`) merge key-by-key.
        Arrays (`inputs`, `outputs`, `headers`, `environment`) replace in full
        when the key is present — send the complete list, including entries you
        are not changing. `availability` is the one null-delete: omit it to
        leave the rule untouched, send `null` to detach, send an object to
        replace.

        For `api` and `code` tools, contract, control, and implementation
        are writable.

        Renaming an input or output returns `422` (the name is the identity
        other entities hold). Editing `key`, `source`, or `is_visible_to_llm`
        is allowed. Authorization headers stay stripped on read-back.
      tags:
        - Tools
      parameters:
        - name: tool_id
          in: path
          description: The tool's id
          required: true
          schema:
            type: string
            format: id
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The updated tool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '400':
          description: Bad Request — the path is not a well-formed id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Authorization Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Tool not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: Conflict — the new name collides with another api or code tool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable — illegal write for this tool type, rename of an input or output, or validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolPatch'
servers:
  - url: https://example.ada.support/api
    description: Production
webhooks:
  end-user-created-webhook:
    post:
      operationId: end-user-created-webhook
      summary: 'Webhook: End user created'
      description: A webhook sent when a new end user is created
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserCreatedWebhookPayload'
  end-user-updated-webhook:
    post:
      operationId: end-user-updated-webhook
      summary: 'Webhook: End user updated'
      description: A webhook sent when an end user is updated
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndUserUpdatedWebhookPayload'
  audit-log-webhook:
    post:
      operationId: audit-log-webhook
      summary: 'Webhook: Audit log event'
      description: >-
        A webhook sent when a configuration change is recorded in the Audit log. Delivery is best-effort; use the Audit
        log pull API (`GET /api/v2/analytics/audit-log/events/`) as the durable record to reconcile any events that were
        not delivered.
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditLogWebhookPayload'
  conversation-created-webhook:
    post:
      operationId: conversation-created-webhook
      summary: 'Webhook: Conversation created'
      description: A webhook sent when a conversation is created
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreatedWebhookPayload'
  conversation-message-webhook:
    post:
      operationId: conversation-message-webhook
      summary: 'Webhook: Conversation message'
      description: A webhook sent when a message is sent to a conversation
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationMessageWebhookPayload'
  conversation-ended-webhook:
    post:
      operationId: conversation-ended-webhook
      summary: 'Webhook: Conversation ended'
      description: A webhook sent when a conversation ends
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationEndedWebhookPayload'
  conversation-handoff-ended-webhook:
    post:
      operationId: conversation-handoff-ended-webhook
      summary: 'Webhook: Conversation handoff ended'
      description: A webhook sent when a handoff is ended
      responses:
        '200':
          description: Webhook received successfully
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationHandoffEndedWebhookPayload'
components:
  schemas:
    KnowledgeSourceResponseMetadata:
      type: object
      properties: {}
      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.
      title: KnowledgeSourceResponseMetadata
    KnowledgeSourceResponseStatus:
      type: string
      enum:
        - deleting
        - delete_failed
      description: >-
        Deletion lifecycle status of the knowledge source: `deleting` while an asynchronous deletion is in progress,
        `delete_failed` if the deletion failed. `null` when no deletion is in progress.
      title: KnowledgeSourceResponseStatus
    KnowledgeSourceResponse:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the knowledge source
        external_id:
          type:
            - string
            - 'null'
          description: An external identifier for the knowledge source
        name:
          type: string
          minLength: 1
          description: The name of the knowledge source
        metadata:
          oneOf:
            - $ref: '#/components/schemas/KnowledgeSourceResponseMetadata'
            - type: 'null'
          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.
        created:
          type: string
          format: date-time
          description: The date the knowledge source was created
        updated:
          type: string
          format: date-time
          description: The date the knowledge source was last updated
        last_sync:
          type: string
          format: date-time
          description: The date the knowledge source was last synchronized
        status:
          $ref: '#/components/schemas/KnowledgeSourceResponseStatus'
          description: >-
            Deletion lifecycle status of the knowledge source: `deleting` while an asynchronous deletion is in progress,
            `delete_failed` if the deletion failed. `null` when no deletion is in progress.
      required:
        - id
        - name
      title: KnowledgeSourceResponse
    knowledge_sources_list_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeSourceResponse'
      title: knowledge_sources_list_Response_200
    ErrorsErrorsItems:
      type: object
      properties:
        type:
          type: string
          description: The error type
        message:
          type: string
          description: The error message
        details:
          type:
            - string
            - 'null'
          description: Extra information about the error
      required:
        - type
        - message
      title: ErrorsErrorsItems
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorsErrorsItems'
          description: A list of errors
      required:
        - errors
      title: Errors
    KnowledgeSourceCreateRequestMetadata:
      type: object
      properties: {}
      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.
      title: KnowledgeSourceCreateRequestMetadata
    KnowledgeSourceCreateRequest:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 160
          description: A unique identifier for the knowledge source
        name:
          type: string
          minLength: 1
          description: The name of the knowledge source
        metadata:
          oneOf:
            - $ref: '#/components/schemas/KnowledgeSourceCreateRequestMetadata'
            - type: 'null'
          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.
      required:
        - id
        - name
      title: KnowledgeSourceCreateRequest
    knowledge_sources_delete_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: knowledge_sources_delete_Response_204
    KnowledgeSourceUpdateRequestMetadata:
      type: object
      properties: {}
      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.
      title: KnowledgeSourceUpdateRequestMetadata
    KnowledgeSourceUpdateRequest:
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 160
          description: A unique identifier for the knowledge source
        name:
          type: string
          minLength: 1
          description: The name of the knowledge source
        metadata:
          oneOf:
            - $ref: '#/components/schemas/KnowledgeSourceUpdateRequestMetadata'
            - type: 'null'
          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.
      title: KnowledgeSourceUpdateRequest
    ArticleLanguage:
      type: string
      enum:
        - ar
        - zh
        - zh-tw
        - da
        - nl
        - en
        - fi
        - fr
        - de
        - he
        - hi
        - id
        - in
        - it
        - ja
        - ko
        - ms
        - 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
      description: The ISO 639-1 language code of the article, defaults to `en`
      title: ArticleLanguage
    KnowledgeArticleResponseMetadata:
      type: object
      properties: {}
      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.
      title: KnowledgeArticleResponseMetadata
    AvailabilityRuleMatch:
      type: string
      enum:
        - all
        - any
      description: Whether all conditions must pass (`all`) or any one condition must pass (`any`).
      title: AvailabilityRuleMatch
    AvailabilityRuleConditionVariable:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: The id of the variable.
      required:
        - id
      description: >-
        The variable to test, referenced by `id`. Look up the ids for your Agent through the variables endpoint. Not
        every variable can be used in a rule; referencing one that can't returns a `400`.
      title: AvailabilityRuleConditionVariable
    AvailabilityRuleConditionOperator:
      type: string
      enum:
        - equals
        - does_not_equal
        - greater_than
        - less_than
        - starts_with
        - ends_with
        - contains
        - does_not_contain
        - is_set
        - is_not_set
      description: The comparison operator. Unary operators (`is_set`, `is_not_set`) must not include a `value` field.
      title: AvailabilityRuleConditionOperator
    AvailabilityRuleConditionValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: The value to compare against. Omit for unary operators (`is_set`, `is_not_set`).
      title: AvailabilityRuleConditionValue
    AvailabilityRuleCondition:
      type: object
      properties:
        variable:
          $ref: '#/components/schemas/AvailabilityRuleConditionVariable'
          description: >-
            The variable to test, referenced by `id`. Look up the ids for your Agent through the variables endpoint. Not
            every variable can be used in a rule; referencing one that can't returns a `400`.
        operator:
          $ref: '#/components/schemas/AvailabilityRuleConditionOperator'
          description: The comparison operator. Unary operators (`is_set`, `is_not_set`) must not include a `value` field.
        value:
          $ref: '#/components/schemas/AvailabilityRuleConditionValue'
          description: The value to compare against. Omit for unary operators (`is_set`, `is_not_set`).
        case_sensitive:
          type: boolean
          description: >-
            Whether the comparison is case-sensitive. Defaults to `false`. Only meaningful for the equality (`equals`,
            `does_not_equal`) and string (`starts_with`, `ends_with`, `contains`, `does_not_contain`) operators. Omitted
            from responses when `false`.
      required:
        - variable
        - operator
      description: A single condition comparing a variable to a value.
      title: AvailabilityRuleCondition
    AvailabilityRuleConditionGroupMatch:
      type: string
      enum:
        - all
        - any
      description: Whether all conditions must pass (`all`) or any one condition must pass (`any`).
      title: AvailabilityRuleConditionGroupMatch
    AvailabilityRuleConditionGroup:
      type: object
      properties:
        match:
          $ref: '#/components/schemas/AvailabilityRuleConditionGroupMatch'
          description: Whether all conditions must pass (`all`) or any one condition must pass (`any`).
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityRuleCondition'
          description: List of conditions inside this condition group. Must contain at least one entry.
      required:
        - match
        - conditions
      description: >-
        A nested group of conditions inside a rule's top-level `conditions` list. Condition groups may contain only
        `Condition` objects — further nesting is not supported.
      title: AvailabilityRuleConditionGroup
    AvailabilityRuleConditionsItems:
      oneOf:
        - $ref: '#/components/schemas/AvailabilityRuleCondition'
        - $ref: '#/components/schemas/AvailabilityRuleConditionGroup'
      title: AvailabilityRuleConditionsItems
    AvailabilityRule:
      type: object
      properties:
        match:
          $ref: '#/components/schemas/AvailabilityRuleMatch'
          description: Whether all conditions must pass (`all`) or any one condition must pass (`any`).
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityRuleConditionsItems'
          description: >-
            List of conditions or condition groups. Must contain at least one entry. Each entry is either a `Condition`
            object (with `variable`, `operator`, and optional `value`) or a `ConditionGroup` object (with its own
            `match` and nested `conditions` list).
      required:
        - match
        - conditions
      description: >-
        A two-level tree of conditions that determines availability based on variable values during a conversation. The
        root group has a `match` combinator and a list of conditions or condition groups. A rule may contain at most
        1000 conditions in total, counting every condition across the root and all nested condition groups.
      title: AvailabilityRule
    KnowledgeArticleResponse:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 160
          description: A unique identifier for the article
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name or title of the article
        content:
          type: string
          minLength: 1
          description: The content of the article in markdown format
        url:
          type:
            - string
            - 'null'
          format: url
          description: The url of the article
        knowledge_source_id:
          type:
            - string
            - 'null'
          description: The id of the `knowledge_source` the article belongs to
        language:
          $ref: '#/components/schemas/ArticleLanguage'
        tag_ids:
          type: array
          items:
            type: string
            minLength: 1
          description: A list of ids for the tags associated with the article
        created:
          type: string
          format: date-time
          description: The date the article was created in Ada
        updated:
          type: string
          format: date-time
          description: The date the article was last updated in Ada
        external_created:
          type:
            - string
            - 'null'
          format: date-time
          description: The date the article was created in the source system
        external_updated:
          type:
            - string
            - 'null'
          format: date-time
          description: The date the article was last updated in the source system
        enabled:
          type: boolean
          description: Whether the article should be referenced during response generation, defaults to `true`
        metadata:
          oneOf:
            - $ref: '#/components/schemas/KnowledgeArticleResponseMetadata'
            - type: 'null'
          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.
        availability_rules:
          oneOf:
            - $ref: '#/components/schemas/AvailabilityRule'
            - type: 'null'
          description: >-
            Availability rule controlling which articles the AI Agent can access during a conversation. `null` when no
            rule is set.
      required:
        - id
        - name
        - content
      title: KnowledgeArticleResponse
    PaginationMetadata:
      type: object
      properties:
        next_page_url:
          type:
            - string
            - 'null'
          description: The URL to the next page of results
      title: PaginationMetadata
    knowledge_articles_list_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeArticleResponse'
        meta:
          $ref: '#/components/schemas/PaginationMetadata'
      title: knowledge_articles_list_Response_200
    knowledge_articles_delete_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: knowledge_articles_delete_Response_204
    knowledge_articles_deleteById_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: knowledge_articles_deleteById_Response_204
    KnowledgeArticleUpsertRequestMetadata:
      type: object
      properties: {}
      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.
      title: KnowledgeArticleUpsertRequestMetadata
    KnowledgeArticleUpsertRequest:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 160
          description: A unique identifier for the article
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: The name or title of the article
        content:
          type: string
          minLength: 1
          description: The content of the article in markdown format
        url:
          type:
            - string
            - 'null'
          format: url
          description: The url of the article
        knowledge_source_id:
          type: string
          description: The id of the `knowledge_source` the article belongs to
        tag_ids:
          type: array
          items:
            type: string
            minLength: 1
          description: A list of ids for the tags associated with the article
        language:
          type: string
          description: The IETF BCP 47 language code for the article, defaults to `en`
        external_created:
          type:
            - string
            - 'null'
          format: date-time
          description: The date the article was created in the source system
        external_updated:
          type:
            - string
            - 'null'
          format: date-time
          description: The date the article was last updated in the source system
        enabled:
          type: boolean
          description: Whether the article should be referenced during response generation, defaults to `true`
        metadata:
          oneOf:
            - $ref: '#/components/schemas/KnowledgeArticleUpsertRequestMetadata'
            - type: 'null'
          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.
        availability_rules:
          oneOf:
            - $ref: '#/components/schemas/AvailabilityRule'
            - type: 'null'
          description: >-
            Availability rule controlling which articles the AI Agent can access during a conversation. Send a rule
            object to attach or replace a rule, `null` to detach an existing rule, or omit the field to leave any
            existing rule unchanged. A rule may contain at most 1000 conditions in total. See [Availability
            rules](/reference/introduction/availability-rules) for the full schema and examples.
      required:
        - id
        - name
        - content
        - knowledge_source_id
      title: KnowledgeArticleUpsertRequest
    KnowledgeArticleUpsertResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the article was successfully created/updated
        created:
          type: boolean
          description: '`True` if a new article was created, `false` if an existing article was updated'
        id:
          type: string
          minLength: 1
          maxLength: 160
          description: A unique identifier for the article
      required:
        - id
      title: KnowledgeArticleUpsertResponse
    ArticleTag:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 40
          description: A unique identifier for the tag
        name:
          type: string
          minLength: 1
          maxLength: 40
          description: The name of the tag
      required:
        - id
        - name
      title: ArticleTag
    knowledge_tags_list_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ArticleTag'
      title: knowledge_tags_list_Response_200
    knowledge_tags_delete_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: knowledge_tags_delete_Response_204
    ArticleTagUpsertResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the article tag was successfully created/updated
        created:
          type: boolean
          description: '`True` if a new article tag was created, `false` if an existing article tag was updated'
        id:
          type: string
          description: The id of the article tag
      required:
        - success
        - created
        - id
      title: ArticleTagUpsertResponse
    EndUserProfileSystemProperties:
      type: object
      properties:
        sunshine_user_id:
          type:
            - string
            - 'null'
          description: The Sunshine Conversations user id for the end user
      description: Read-only profile information set by Ada
      title: EndUserProfileSystemProperties
    EndUserProfile:
      type: object
      properties:
        first_name:
          type:
            - string
            - 'null'
          description: The end user's first name
        last_name:
          type:
            - string
            - 'null'
          description: The end user's last name
        display_name:
          type:
            - string
            - 'null'
          description: The end user's display name
        avatar:
          type:
            - string
            - 'null'
          description: URL to the end user's avatar image
        email:
          type:
            - string
            - 'null'
          description: The end user's email address
        language:
          type:
            - string
            - 'null'
          description: The end user's language in BCP 47 format
        metadata:
          type: object
          additionalProperties:
            description: Any type
          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`
        system_properties:
          $ref: '#/components/schemas/EndUserProfileSystemProperties'
          description: Read-only profile information set by Ada
      description: The end user's profile information
      title: EndUserProfile
    EndUser:
      type: object
      properties:
        end_user_id:
          type: string
          description: The unique Ada-generated id for the end user
        external_id:
          type:
            - string
            - 'null'
          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).
        profile:
          $ref: '#/components/schemas/EndUserProfile'
          description: The end user's profile information
        created_at:
          type: string
          description: The date and time the end user was created
        updated_at:
          type: string
          description: The date and time the end user was updated
      title: EndUser
    EndUserRequestProfileSensitiveMetadataFields:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
      title: EndUserRequestProfileSensitiveMetadataFields
    EndUserRequestProfileSensitiveMetadata:
      type: object
      properties:
        fields:
          type: object
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/EndUserRequestProfileSensitiveMetadataFields'
              - type: 'null'
          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.
      required:
        - fields
      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.
      title: EndUserRequestProfileSensitiveMetadata
    EndUserRequestProfile:
      type: object
      properties:
        first_name:
          type:
            - string
            - 'null'
          description: The end user's first name
        last_name:
          type:
            - string
            - 'null'
          description: The end user's last name
        display_name:
          type:
            - string
            - 'null'
          description: The end user's display name
        avatar:
          type:
            - string
            - 'null'
          description: URL to the end user's avatar image
        email:
          type:
            - string
            - 'null'
          description: The end user's email address
        language:
          type:
            - string
            - 'null'
          description: The end user's language in BCP 47 format
        metadata:
          type:
            - object
            - 'null'
          additionalProperties:
            description: Any type
          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 10KB.</br>
        sensitive_metadata:
          oneOf:
            - $ref: '#/components/schemas/EndUserRequestProfileSensitiveMetadata'
            - type: 'null'
          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.
      description: The end user's profile information
      title: EndUserRequestProfile
    EndUserRequest:
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 36
          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).
        profile:
          $ref: '#/components/schemas/EndUserRequestProfile'
          description: The end user's profile information
      required:
        - profile
      title: EndUserRequest
    CursorPaginationMetadata:
      type: object
      properties:
        next_page_url:
          type: string
          format: url
          description: Link to the next page of data using a cursor value
      description: Metadata returned with the results including but not limited to a link to the next page of data
      title: CursorPaginationMetadata
    EndUsers:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EndUser'
          description: The list of end user profiles
        meta:
          $ref: '#/components/schemas/CursorPaginationMetadata'
      title: EndUsers
    End Users_getEndUsers_Response_200:
      oneOf:
        - $ref: '#/components/schemas/EndUser'
        - $ref: '#/components/schemas/EndUsers'
      title: End Users_getEndUsers_Response_200
    CreateEndUserRequestProfileSensitiveMetadataFields:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
      title: CreateEndUserRequestProfileSensitiveMetadataFields
    CreateEndUserRequestProfileSensitiveMetadata:
      type: object
      properties:
        fields:
          type: object
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/CreateEndUserRequestProfileSensitiveMetadataFields'
              - type: 'null'
          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.
      required:
        - fields
      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.
      title: CreateEndUserRequestProfileSensitiveMetadata
    CreateEndUserRequestProfile:
      type: object
      properties:
        first_name:
          type:
            - string
            - 'null'
          description: The end user's first name
        last_name:
          type:
            - string
            - 'null'
          description: The end user's last name
        display_name:
          type:
            - string
            - 'null'
          description: The end user's display name
        avatar:
          type:
            - string
            - 'null'
          description: URL to the end user's avatar image
        email:
          type:
            - string
            - 'null'
          description: The end user's email address
        language:
          type:
            - string
            - 'null'
          description: The end user's language in BCP 47 format
        metadata:
          type:
            - object
            - 'null'
          additionalProperties:
            description: Any type
          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 10KB.</br>
        sensitive_metadata:
          oneOf:
            - $ref: '#/components/schemas/CreateEndUserRequestProfileSensitiveMetadata'
            - type: 'null'
          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.
      description: The end user's profile information. Optional — omitting profile creates a blank end user.
      title: CreateEndUserRequestProfile
    CreateEndUserRequest:
      type: object
      properties:
        external_id:
          type:
            - string
            - 'null'
          maxLength: 36
          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).
        profile:
          $ref: '#/components/schemas/CreateEndUserRequestProfile'
          description: The end user's profile information. Optional — omitting profile creates a blank end user.
      title: CreateEndUserRequest
    DeletionIdentifierType:
      type: string
      enum:
        - email
        - chatter_id
        - external_id
        - end_user_id
        - variable_match
      description: The kind of identifier supplied. `variable_match` selects every end user whose stored variable equals the value.
      title: DeletionIdentifierType
    DeletionIdentifier:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DeletionIdentifierType'
        value:
          type: string
          description: >-
            The identifier value. Email values are normalized and matched case-insensitively; `external_id` values are
            trimmed and lowercased at intake.
        variable:
          type:
            - string
            - 'null'
          description: >-
            Name of the stored variable to match against `value`. Required only when `type` is `variable_match`; leave
            null for all other types.
      required:
        - type
        - value
      description: A single reference to the end user(s) whose data should be erased.
      title: DeletionIdentifier
    DeletionRequest:
      type: object
      properties:
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/DeletionIdentifier'
          description: The identifiers to erase. At least one is required, and a single request accepts at most 1000.
        client_reference:
          type:
            - string
            - 'null'
          description: >-
            Optional caller-supplied reference echoed back on the job. It is also the idempotency key: two identical
            requests that set the same reference within 24 hours resolve to the same job. Requests that omit it are not
            deduplicated.
      required:
        - identifiers
      title: DeletionRequest
    DeletionJobStatus:
      type: string
      enum:
        - queued
        - in_progress
        - completed
        - partial
        - failed
      description: >-
        Lifecycle state of a deletion job. `queued` and `in_progress` are non-terminal; `completed`, `partial`, and
        `failed` are terminal.
      title: DeletionJobStatus
    DeletionRequestAccepted:
      type: object
      properties:
        job_id:
          type: string
          description: Identifier of the created deletion job. Use it to poll job status.
        status:
          $ref: '#/components/schemas/DeletionJobStatus'
        submitted_count:
          type: integer
          description: Number of identifiers received in the request.
        created_at:
          type: string
          format: date-time
          description: Time the job was created, in ISO 8601 format.
      description: Acknowledgment returned when a deletion request is accepted for processing.
      title: DeletionRequestAccepted
    IdentifierDispositionDisposition:
      type: string
      enum:
        - accepted
        - not_found
        - invalid
        - exceeds_limit
        - duplicate
      description: >-
        How the identifier was handled. `accepted` identifiers are queued for erasure; the other values indicate the
        identifier contributed no erasure.
      title: IdentifierDispositionDisposition
    IdentifierDisposition:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DeletionIdentifierType'
        value:
          type: string
          description: The identifier value as submitted.
        variable:
          type:
            - string
            - 'null'
          description: The matched variable name, or null when not applicable.
        disposition:
          $ref: '#/components/schemas/IdentifierDispositionDisposition'
          description: >-
            How the identifier was handled. `accepted` identifiers are queued for erasure; the other values indicate the
            identifier contributed no erasure.
        matched_chatters:
          type: integer
          minimum: 0
          maximum: 1000000
          description: Number of end users matched by this identifier.
        reason:
          type:
            - string
            - 'null'
          description: >-
            Human-readable explanation for a non-accepted disposition. Always set for `invalid` and `exceeds_limit`, and
            for `not_found` on ID-based identifiers; may be null for a `not_found` `email` or `variable_match` selector,
            and for `accepted`/`duplicate`. Do not assume it is non-null from `disposition` alone.
      description: The outcome for one submitted identifier.
      title: IdentifierDisposition
    DeletionJob:
      type: object
      properties:
        job_id:
          type: string
          description: Identifier of the deletion job.
        type:
          type: string
          description: The job type.
        client_reference:
          type:
            - string
            - 'null'
          description: The caller-supplied reference from the original request, or null.
        status:
          $ref: '#/components/schemas/DeletionJobStatus'
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/IdentifierDisposition'
          description: >-
            Per-identifier outcomes. Inspect this array to understand exactly what was erased, rather than relying on
            the top-level status alone.
        created_at:
          type: string
          format: date-time
          description: Time the job was created, in ISO 8601 format.
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Time the job reached a terminal state, in ISO 8601 format, or null while the job is still running.
        failure_reason:
          type:
            - string
            - 'null'
          description: >-
            Opaque, machine-readable diagnostic present only when `status` is `failed`, or null otherwise. This value is
            subject to change; to understand outcomes per identifier, inspect each identifier's `disposition` and
            `reason`.
      description: Full state of a deletion job, including the per-identifier outcomes.
      title: DeletionJob
    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)
      title: IntegrationIdentifierField
    IntegrationIconUrl:
      type:
        - string
        - 'null'
      format: url
      minLength: 1
      description: The URL of the icon that should be displayed with your integration
      title: IntegrationIconUrl
    IntegrationCallToAction:
      type:
        - string
        - 'null'
      minLength: 1
      description: The call to action text
      title: IntegrationCallToAction
    PlatformIntegrationTagsItems:
      type: string
      enum:
        - knowledge
      title: PlatformIntegrationTagsItems
    PlatformIntegrationErrorCodes:
      type: object
      properties: {}
      description: >-
        An object containing error codes and their corresponding error message the integration may return to the OAuth
        failure page to be displayed
      title: PlatformIntegrationErrorCodes
    PlatformIntegrationConfigurationFields:
      type: object
      properties: {}
      description: >-
        A json-schema describing the settings fields that a user should be presented with when installing the
        integration
      title: PlatformIntegrationConfigurationFields
    PlatformIntegration:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the integration
        status:
          type: string
          description: The current state of the integration (development, approved, archived)
        created:
          type: string
          format: date-time
          description: The date the integration was created
        updated:
          type: string
          format: date-time
          description: The date the integration was last updated
        identifier_field_path:
          $ref: '#/components/schemas/IntegrationIdentifierField'
        icon_url:
          $ref: '#/components/schemas/IntegrationIconUrl'
        call_to_action:
          $ref: '#/components/schemas/IntegrationCallToAction'
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: The name of the integration
        description:
          type: string
          minLength: 1
          description: A description of what the integration does and how to use it
        author:
          type: string
          minLength: 1
          maxLength: 160
          description: The name of the integration developer
        contact:
          type: string
          minLength: 1
          description: The URL or email address where users of the integration can reach out for support
        uninstallation_url:
          type: string
          format: url
          minLength: 1
          description: The `delete` endpoint that initiates the uninstallation flow for the integration
        oauth_callback_url:
          type: string
          format: url
          minLength: 1
          description: The `get` endpoint that will be invoked after OAuth authorization
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PlatformIntegrationTagsItems'
          description: A list of tags that describe the type of integration
        error_codes:
          oneOf:
            - $ref: '#/components/schemas/PlatformIntegrationErrorCodes'
            - type: 'null'
          description: >-
            An object containing error codes and their corresponding error message the integration may return to the
            OAuth failure page to be displayed
        scopes:
          type: array
          items:
            type: string
            minLength: 1
          description: The list of OAuth token permissions the integration requests when installed
        configuration_fields:
          $ref: '#/components/schemas/PlatformIntegrationConfigurationFields'
          description: >-
            A json-schema describing the settings fields that a user should be presented with when installing the
            integration
      required:
        - id
        - status
        - identifier_field_path
        - name
        - description
        - author
        - contact
        - uninstallation_url
        - oauth_callback_url
        - tags
        - scopes
        - configuration_fields
      title: PlatformIntegration
    Platform Integrations_getPlatformIntegrations_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PlatformIntegration'
        meta:
          $ref: '#/components/schemas/PaginationMetadata'
      title: Platform Integrations_getPlatformIntegrations_Response_200
    PlatformIntegrationCreateRequestTagsItems:
      type: string
      enum:
        - knowledge
      title: PlatformIntegrationCreateRequestTagsItems
    PlatformIntegrationCreateRequestErrorCodes:
      type: object
      properties: {}
      description: >-
        An object containing error codes and their corresponding error message the integration may return to the OAuth
        failure page to be displayed
      title: PlatformIntegrationCreateRequestErrorCodes
    PlatformIntegrationCreateRequestConfigurationFields:
      type: object
      properties: {}
      description: >-
        A json-schema describing the settings fields that a user should be presented with when installing the
        integration
      title: PlatformIntegrationCreateRequestConfigurationFields
    PlatformIntegrationCreateRequest:
      type: object
      properties:
        identifier_field_path:
          $ref: '#/components/schemas/IntegrationIdentifierField'
        icon_url:
          $ref: '#/components/schemas/IntegrationIconUrl'
        call_to_action:
          $ref: '#/components/schemas/IntegrationCallToAction'
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: The name of the integration
        description:
          type: string
          minLength: 1
          description: A description of what the integration does and how to use it
        author:
          type: string
          minLength: 1
          maxLength: 160
          description: The name of the integration developer
        contact:
          type: string
          minLength: 1
          description: The URL or email address where users of the integration can reach out for support
        uninstallation_url:
          type: string
          format: url
          minLength: 1
          description: The `delete` endpoint that initiates the uninstallation flow for the integration
        oauth_callback_url:
          type: string
          format: url
          minLength: 1
          description: The `get` endpoint that will be invoked after OAuth authorization
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PlatformIntegrationCreateRequestTagsItems'
          description: A list of tags that describe the type of integration
        error_codes:
          oneOf:
            - $ref: '#/components/schemas/PlatformIntegrationCreateRequestErrorCodes'
            - type: 'null'
          description: >-
            An object containing error codes and their corresponding error message the integration may return to the
            OAuth failure page to be displayed
        scopes:
          type: array
          items:
            type: string
            minLength: 1
          description: The list of OAuth token permissions the integration requests when installed
        configuration_fields:
          $ref: '#/components/schemas/PlatformIntegrationCreateRequestConfigurationFields'
          description: >-
            A json-schema describing the settings fields that a user should be presented with when installing the
            integration
      required:
        - identifier_field_path
        - name
        - description
        - author
        - contact
        - uninstallation_url
        - oauth_callback_url
        - tags
        - scopes
        - configuration_fields
      title: PlatformIntegrationCreateRequest
    Platform Integrations_createPlatformIntegration_Response_200:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the integration
        status:
          type: string
          description: The current state of the integration (development, approved, archived)
        created:
          type: string
          format: date-time
          description: The date the integration was created
        updated:
          type: string
          format: date-time
          description: The date the integration was last updated
        identifier_field_path:
          $ref: '#/components/schemas/IntegrationIdentifierField'
        icon_url:
          $ref: '#/components/schemas/IntegrationIconUrl'
        call_to_action:
          $ref: '#/components/schemas/IntegrationCallToAction'
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: The name of the integration
        description:
          type: string
          minLength: 1
          description: A description of what the integration does and how to use it
        author:
          type: string
          minLength: 1
          maxLength: 160
          description: The name of the integration developer
        contact:
          type: string
          minLength: 1
          description: The URL or email address where users of the integration can reach out for support
        uninstallation_url:
          type: string
          format: url
          minLength: 1
          description: The `delete` endpoint that initiates the uninstallation flow for the integration
        oauth_callback_url:
          type: string
          format: url
          minLength: 1
          description: The `get` endpoint that will be invoked after OAuth authorization
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PlatformIntegrationTagsItems'
          description: A list of tags that describe the type of integration
        error_codes:
          oneOf:
            - $ref: '#/components/schemas/PlatformIntegrationErrorCodes'
            - type: 'null'
          description: >-
            An object containing error codes and their corresponding error message the integration may return to the
            OAuth failure page to be displayed
        scopes:
          type: array
          items:
            type: string
            minLength: 1
          description: The list of OAuth token permissions the integration requests when installed
        configuration_fields:
          $ref: '#/components/schemas/PlatformIntegrationConfigurationFields'
          description: >-
            A json-schema describing the settings fields that a user should be presented with when installing the
            integration
        client_secret:
          type: string
          description: The OAuth client secret for the integration
      required:
        - id
        - status
        - identifier_field_path
        - name
        - description
        - author
        - contact
        - uninstallation_url
        - oauth_callback_url
        - tags
        - scopes
        - configuration_fields
      title: Platform Integrations_createPlatformIntegration_Response_200
    IntegrationCommonFieldsTagsItems:
      type: string
      enum:
        - knowledge
      title: IntegrationCommonFieldsTagsItems
    IntegrationCommonFieldsErrorCodes:
      type: object
      properties: {}
      description: >-
        An object containing error codes and their corresponding error message the integration may return to the OAuth
        failure page to be displayed
      title: IntegrationCommonFieldsErrorCodes
    IntegrationCommonFieldsConfigurationFields:
      type: object
      properties: {}
      description: >-
        A json-schema describing the settings fields that a user should be presented with when installing the
        integration
      title: IntegrationCommonFieldsConfigurationFields
    PlatformIntegrationUpdateRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: The name of the integration
        description:
          type: string
          minLength: 1
          description: A description of what the integration does and how to use it
        author:
          type: string
          minLength: 1
          maxLength: 160
          description: The name of the integration developer
        contact:
          type: string
          minLength: 1
          description: The URL or email address where users of the integration can reach out for support
        uninstallation_url:
          type: string
          format: url
          minLength: 1
          description: The `delete` endpoint that initiates the uninstallation flow for the integration
        oauth_callback_url:
          type: string
          format: url
          minLength: 1
          description: The `get` endpoint that will be invoked after OAuth authorization
        tags:
          type: array
          items:
            $ref: '#/components/schemas/IntegrationCommonFieldsTagsItems'
          description: A list of tags that describe the type of integration
        error_codes:
          oneOf:
            - $ref: '#/components/schemas/IntegrationCommonFieldsErrorCodes'
            - type: 'null'
          description: >-
            An object containing error codes and their corresponding error message the integration may return to the
            OAuth failure page to be displayed
        scopes:
          type: array
          items:
            type: string
            minLength: 1
          description: The list of OAuth token permissions the integration requests when installed
        configuration_fields:
          $ref: '#/components/schemas/IntegrationCommonFieldsConfigurationFields'
          description: >-
            A json-schema describing the settings fields that a user should be presented with when installing the
            integration
        identifier_field_path:
          $ref: '#/components/schemas/IntegrationIdentifierField'
        icon_url:
          $ref: '#/components/schemas/IntegrationIconUrl'
        call_to_action:
          $ref: '#/components/schemas/IntegrationCallToAction'
      title: PlatformIntegrationUpdateRequest
    PlatformIntegrationInstallationConfiguration:
      type: object
      properties: {}
      description: The configuration settings for the integration
      title: PlatformIntegrationInstallationConfiguration
    PlatformIntegrationInstallation:
      type: object
      properties:
        id:
          type: string
          format: id
          description: The unique identifier for the integration installation
        platform_integration_id:
          type: string
          format: id
          description: The unique identifier for the integration
        created:
          type: string
          format: date-time
          description: The date and time the installation was created
        updated:
          type: string
          format: date-time
          description: The date and time the installation was last updated
        configuration:
          $ref: '#/components/schemas/PlatformIntegrationInstallationConfiguration'
          description: The configuration settings for the integration
        status:
          type: string
          description: The current state of the integration installation (incomplete, complete)
      title: PlatformIntegrationInstallation
    PlatformIntegrationInstallationUpdateRequestStatus:
      type: string
      enum:
        - complete
        - incomplete
      description: The new status of the installation
      title: PlatformIntegrationInstallationUpdateRequestStatus
    PlatformIntegrationInstallationUpdateRequest:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/PlatformIntegrationInstallationUpdateRequestStatus'
          description: The new status of the installation
      title: PlatformIntegrationInstallationUpdateRequest
    AuditLogEvent:
      type: object
      properties:
        id:
          type: string
          description: Globally unique event id (uuid4)
        timestamp:
          type: string
          format: date-time
          description: When the change occurred (ISO 8601, UTC, millisecond precision)
        actor_email:
          type: string
          description: >-
            Email of the user who made the change, or the owner of a dashboard-created Platform API key. Empty for
            system and service-token actors.
        actor_name:
          type: string
          description: Display name of the actor; empty when unavailable
        actor_user_id:
          type: string
          description: >-
            User id of the actor. For an API key, the id of the user who created the key. Empty for system and
            service-token actors.
        entity_type:
          type: string
          description: The type of entity that was changed
        entity_id:
          type: string
          description: The id of the entity that was changed
        entity_name:
          type: string
          description: A human-readable name for the changed entity
        activity:
          type: string
          description: >-
            What happened to the entity. One of `created`, `updated`, `deleted`, `executed`, `invited`, `activated`, or
            `deactivated`.
        interface:
          type: string
          description: >-
            Where the change originated, such as `dashboard`, `api`, `mcp`, `cli`, `import`, `export`, or `system`
            (background jobs and Ada's internal processing).
        context_ip:
          type: string
          description: Source IP address of the request that made the change
        context_user_agent:
          type: string
          description: User agent string of the request that made the change
        api_key_name:
          type: string
          description: Name of the API key used, when the change was made by a dashboard-created Platform API key; empty otherwise.
      required:
        - id
        - timestamp
        - entity_type
        - entity_id
        - activity
      description: >-
        A single Audit log event: one configuration change recorded for the account. Empty-string fields mean the value
        was unavailable for that event (for example, a system actor has no email).
      title: AuditLogEvent
    AuditLogEventListMeta:
      type: object
      properties:
        next_page_url:
          type:
            - string
            - 'null'
          description: >-
            URL for the next page of results, or `null` on the last or empty page. Replay it unchanged to keep the time
            window and the cursor constant across pages.
      description: Pagination metadata
      title: AuditLogEventListMeta
    AuditLogEventList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AuditLogEvent'
          description: The page of Audit log events (at most `limit` items)
        meta:
          $ref: '#/components/schemas/AuditLogEventListMeta'
          description: Pagination metadata
      required:
        - data
        - meta
      description: A cursor-paginated page of Audit log events
      title: AuditLogEventList
    V2ChannelsGetParametersType:
      type: string
      enum:
        - custom
        - native
      title: V2ChannelsGetParametersType
    V2ChannelsGetParametersModality:
      type: string
      enum:
        - messaging
        - email
        - voice
      title: V2ChannelsGetParametersModality
    BaseChannelModality:
      type: string
      enum:
        - messaging
        - email
        - voice
      description: The modality of the channel
      title: BaseChannelModality
    BaseChannelCapabilities:
      type: object
      properties:
        markdown:
          type: boolean
          default: false
          description: Preserve Markdown (bold, italic, and links) in replies instead of flattening to plain text.
      description: >-
        What the channel's surface can render. The AI Agent tailors replies to the declared capabilities. Omitted fields
        default to false. Read-only on native channels, whose capabilities are fixed by the surface.
      title: BaseChannelCapabilities
    CustomChannelType:
      type: string
      enum:
        - custom
      description: The type of the channel
      title: CustomChannelType
    CustomChannelMetadata:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
          format: double
      title: CustomChannelMetadata
    NativeChannelType:
      type: string
      enum:
        - native
      description: The type of the channel
      title: NativeChannelType
    Channel:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CustomChannelType'
              description: The type of the channel
            id:
              type: string
              format: id
              description: The channel ID
            name:
              type: string
              description: The name of the channel
            description:
              type: string
              description: A description of the channel
            modality:
              $ref: '#/components/schemas/BaseChannelModality'
              description: The modality of the channel
            capabilities:
              $ref: '#/components/schemas/BaseChannelCapabilities'
              description: >-
                What the channel's surface can render. The AI Agent tailors replies to the declared capabilities.
                Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the
                surface.
            metadata:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/CustomChannelMetadata'
              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)
            created_at:
              type: string
              format: date-time
              description: The date and time the channel was created
          required:
            - type
            - name
            - description
            - modality
          description: custom variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/NativeChannelType'
              description: The type of the channel
            id:
              type: string
              description: The channel ID
            name:
              type: string
              description: The name of the channel
            description:
              type: string
              description: A description of the channel
            modality:
              $ref: '#/components/schemas/BaseChannelModality'
              description: The modality of the channel
            capabilities:
              $ref: '#/components/schemas/BaseChannelCapabilities'
              description: >-
                What the channel's surface can render. The AI Agent tailors replies to the declared capabilities.
                Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the
                surface.
          required:
            - type
            - name
            - description
            - modality
          description: native variant
      discriminator:
        propertyName: type
      title: Channel
    Channels_getChannels_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Channel'
        meta:
          $ref: '#/components/schemas/PaginationMetadata'
      title: Channels_getChannels_Response_200
    CustomChannel:
      type: object
      properties:
        id:
          type: string
          format: id
          description: The channel ID
        type:
          $ref: '#/components/schemas/CustomChannelType'
          description: The type of the channel
        name:
          type: string
          description: The name of the channel
        description:
          type: string
          description: A description of the channel
        modality:
          $ref: '#/components/schemas/BaseChannelModality'
          description: The modality of the channel
        capabilities:
          $ref: '#/components/schemas/BaseChannelCapabilities'
          description: >-
            What the channel's surface can render. The AI Agent tailors replies to the declared capabilities. Omitted
            fields default to false. Read-only on native channels, whose capabilities are fixed by the surface.
        metadata:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CustomChannelMetadata'
          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)
        created_at:
          type: string
          format: date-time
          description: The date and time the channel was created
      required:
        - name
        - description
        - modality
      title: CustomChannel
    UpdateChannelCapabilities:
      type: object
      properties:
        markdown:
          type: boolean
          description: Preserve Markdown (bold, italic, and links) in replies instead of flattening to plain text.
      description: Capabilities to update. Only the fields you include are changed; omitted fields keep their current value.
      title: UpdateChannelCapabilities
    UpdateChannel:
      type: object
      properties:
        capabilities:
          $ref: '#/components/schemas/UpdateChannelCapabilities'
          description: Capabilities to update. Only the fields you include are changed; omitted fields keep their current value.
      required:
        - capabilities
      description: Fields that can be updated on an existing custom channel
      title: UpdateChannel
    EmailConversationCreateRequestMetadata:
      type: object
      properties: {}
      description: >-
        Any metadata associated with the conversation, up to 4 KB. All metadata passed through this field will appear as
        metavariables in your dashboard.
      title: EmailConversationCreateRequestMetadata
    EmailConversationCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: The customer's full name
        subject:
          type: string
          description: The subject of the customer's inquiry; used as the subject for the AI Agent's reply
        reply_to:
          type: string
          description: The customer's email address
        text:
          type: string
          description: The customer's inquiry, limited to 10 KB
        reply_as:
          type: string
          description: >-
            The company email address you want to use to reply to the customer. Defaults to the Ada provided email
            address.
        cc:
          type: array
          items:
            type: string
          description: The email addresses in the email's CC field
        metadata:
          $ref: '#/components/schemas/EmailConversationCreateRequestMetadata'
          description: >-
            Any metadata associated with the conversation, up to 4 KB. All metadata passed through this field will
            appear as metavariables in your dashboard.
      required:
        - name
        - subject
        - reply_to
      title: EmailConversationCreateRequest
    EmailConversationCreateResponse:
      type: object
      properties:
        conversation_id:
          type: string
          description: The Ada-generated conversation id
      title: EmailConversationCreateResponse
    ConversationCreateRequestMetadata:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
          format: double
      title: ConversationCreateRequestMetadata
    ConversationCreateRequest:
      type: object
      properties:
        channel_id:
          type: string
          format: id
          description: The ID of the channel to create a conversation in
        end_user_id:
          type: string
          format: id
          description: >-
            The ID of the end user participating in the conversation. If not provided, the system will create a new end
            user automatically.
        metadata:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ConversationCreateRequestMetadata'
          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)
      required:
        - channel_id
      title: ConversationCreateRequest
    ConversationStatus:
      type: string
      enum:
        - active
        - ended
      description: The status of the conversation
      title: ConversationStatus
    ConversationMetadata:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
          format: double
      title: ConversationMetadata
    Conversation:
      type: object
      properties:
        id:
          type: string
          format: id
          description: The ID of the conversation
        channel_id:
          type: string
          description: The ID of the channel
        end_user_id:
          type: string
          format: id
          description: The ID of the end user participating in the conversation
        status:
          $ref: '#/components/schemas/ConversationStatus'
          description: The status of the conversation
        created_at:
          type: string
          description: The date and time the conversation was created
        updated_at:
          type: string
          description: The date and time the conversation was last updated
        metadata:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ConversationMetadata'
          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)
      title: Conversation
    ConversationPatchRequestMetadata:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
          format: double
      title: ConversationPatchRequestMetadata
    ConversationPatchRequest:
      type: object
      properties:
        metadata:
          type: object
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/ConversationPatchRequestMetadata'
              - type: 'null'
          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
      required:
        - metadata
      title: ConversationPatchRequest
    MessageLogsType:
      type: string
      enum:
        - message_logs
      description: The type of the message
      title: MessageLogsType
    MessageLogsAuthorRole:
      type: string
      enum:
        - end_user
        - ai_agent
        - human_agent
      description: The author's role
      title: MessageLogsAuthorRole
    MessageLogsAuthor:
      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.
        role:
          $ref: '#/components/schemas/MessageLogsAuthorRole'
          description: The author's role
        avatar:
          type:
            - string
            - 'null'
          description: The URL of the author's avatar
        display_name:
          type:
            - string
            - 'null'
          description: The author's display name
      description: Information about the message author
      title: MessageLogsAuthor
    TextContentType:
      type: string
      enum:
        - text
      description: The type of the message
      title: TextContentType
    TextContent:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/TextContentType'
          description: The type of the message
        body:
          type: string
          description: The body of the message
      required:
        - type
        - body
      description: The content of the text message
      title: TextContent
    LinkContentType:
      type: string
      enum:
        - link
      description: The type of the message
      title: LinkContentType
    LinkContent:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/LinkContentType'
          description: The type of the message
        url:
          type: string
          description: The link's URL
        link_text:
          type:
            - string
            - 'null'
          description: Text that can be used to display the link
      description: The content of a standalone link style messages, such as CSAT
      title: LinkContent
    FileContentType:
      type: string
      enum:
        - file
      description: The type of the message
      title: FileContentType
    FileContent:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/FileContentType'
          description: The type of the message
        url:
          type: string
          format: uri
          description: Presigned URL from the attachment upload endpoint (valid for 7 days)
        mime_type:
          type: string
          description: MIME type of the file
        filename:
          type: string
          description: Name of the file
      required:
        - type
        - url
        - mime_type
        - filename
      description: The content of a file message
      title: FileContent
    MessageLogsContent:
      oneOf:
        - $ref: '#/components/schemas/TextContent'
        - $ref: '#/components/schemas/LinkContent'
        - $ref: '#/components/schemas/FileContent'
      description: 'The message content. The structure varies based on the `type` field. Supported types: text, link, file.'
      title: MessageLogsContent
    MessageLogs:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/MessageLogsType'
          description: The type of the message
        message_id:
          type: string
          description: The ID of the message log
        created_at:
          type: string
          description: The date and time the message was created
        author:
          $ref: '#/components/schemas/MessageLogsAuthor'
          description: Information about the message author
        content:
          $ref: '#/components/schemas/MessageLogsContent'
          description: 'The message content. The structure varies based on the `type` field. Supported types: text, link, file.'
      title: MessageLogs
    MessageEvents:
      oneOf:
        - $ref: '#/components/schemas/MessageLogs'
      title: MessageEvents
    MessageList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MessageEvents'
          description: List of messages in the conversation
        meta:
          $ref: '#/components/schemas/PaginationMetadata'
      required:
        - data
        - meta
      title: MessageList
    ConversationMessageAuthorRole:
      type: string
      enum:
        - end_user
        - human_agent
      description: The author's role
      title: ConversationMessageAuthorRole
    ConversationMessageAuthor:
      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`.
        role:
          $ref: '#/components/schemas/ConversationMessageAuthorRole'
          description: The author's role
        avatar:
          type:
            - string
            - 'null'
          description: The URL of the author's avatar
        display_name:
          type:
            - string
            - 'null'
          description: The author's display name. Required when the role is `human_agent`.
      required:
        - role
      description: Information about the message author
      title: ConversationMessageAuthor
    MessageCreateRequestContent:
      oneOf:
        - $ref: '#/components/schemas/TextContent'
        - $ref: '#/components/schemas/FileContent'
      description: The message content
      title: MessageCreateRequestContent
    MessageCreateRequest:
      type: object
      properties:
        author:
          $ref: '#/components/schemas/ConversationMessageAuthor'
        content:
          $ref: '#/components/schemas/MessageCreateRequestContent'
          description: The message content
      required:
        - author
        - content
      title: MessageCreateRequest
    MessageContent:
      oneOf:
        - $ref: '#/components/schemas/TextContent'
        - $ref: '#/components/schemas/FileContent'
      description: The message content
      title: MessageContent
    Message:
      type: object
      properties:
        id:
          type: string
          format: id
          description: The ID of the message
        conversation_id:
          type: string
          format: id
          description: The ID of the conversation
        author:
          $ref: '#/components/schemas/ConversationMessageAuthor'
        content:
          $ref: '#/components/schemas/MessageContent'
          description: The message content
        created_at:
          type: string
          format: date-time
          description: The date and time the message was created
        updated_at:
          type: string
          format: date-time
          description: The date and time the message was updated
      title: Message
    Conversations_endConversation_Response_200:
      type: object
      properties:
        message:
          type: string
      title: Conversations_endConversation_Response_200
    Conversations_endHandoff_Response_200:
      type: object
      properties:
        message:
          type: string
      title: Conversations_endHandoff_Response_200
    AttachmentUploadResponse:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Presigned URL to access the uploaded file (valid for 7 days)
        mime_type:
          type: string
          description: MIME type of the uploaded file
        filename:
          type: string
          description: Name of the uploaded file
      required:
        - url
        - mime_type
        - filename
      title: AttachmentUploadResponse
    Webhook:
      type: object
      properties:
        id:
          type: string
          description: The webhook ID
        url:
          type: string
          format: uri
          description: The URL that will receive webhook events
        description:
          type: string
          description: A description of the webhook
        event_filters:
          type: array
          items:
            type: string
          description: Event types this webhook is subscribed to. If empty, the webhook receives all events
        enabled:
          type: boolean
          description: Whether the webhook is enabled
        created_at:
          type: string
          format: date-time
          description: When the webhook was created
        updated_at:
          type: string
          format: date-time
          description: When the webhook was last updated
      title: Webhook
    V2WebhooksGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties:
        next_page_url:
          type:
            - string
            - 'null'
          description: URL for the next page of results, or null if no pages remain
      title: V2WebhooksGetResponsesContentApplicationJsonSchemaMeta
    Webhook Management_listWebhooks_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        meta:
          $ref: '#/components/schemas/V2WebhooksGetResponsesContentApplicationJsonSchemaMeta'
      title: Webhook Management_listWebhooks_Response_200
    Webhook Management_deleteWebhook_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: Webhook Management_deleteWebhook_Response_204
    Webhook Management_getWebhookSecret_Response_200:
      type: object
      properties:
        key:
          type: string
          description: The webhook signing secret
      title: Webhook Management_getWebhookSecret_Response_200
    Webhook Management_rotateWebhookSecret_Response_200:
      type: object
      properties: {}
      title: Webhook Management_rotateWebhookSecret_Response_200
    V2WebhooksEventTypesGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        name:
          type: string
          description: The event type identifier
        description:
          type: string
          description: Human-readable description of the event type
      title: V2WebhooksEventTypesGetResponsesContentApplicationJsonSchemaDataItems
    Webhook Management_listWebhookEventTypes_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/V2WebhooksEventTypesGetResponsesContentApplicationJsonSchemaDataItems'
      title: Webhook Management_listWebhookEventTypes_Response_200
    PersonaMessageLength:
      type: string
      enum:
        - concise
        - normal
      title: PersonaMessageLength
    Persona:
      type: object
      properties:
        personality:
          type: array
          items:
            type: string
        emoji_usage:
          type: boolean
        allowed_emojis:
          type: string
        default_timezone:
          type: string
        company_description:
          type:
            - string
            - 'null'
        community_guidelines_url:
          type:
            - string
            - 'null'
        message_length:
          $ref: '#/components/schemas/PersonaMessageLength'
        ask_for_more_help:
          type: boolean
        no_customer_pi:
          type: boolean
        no_competitors:
          type: boolean
        competitor_names:
          type:
            - string
            - 'null'
        enable_acknowledgment_messages:
          type: boolean
      required:
        - personality
        - emoji_usage
        - allowed_emojis
        - default_timezone
        - message_length
        - ask_for_more_help
        - no_customer_pi
        - no_competitors
        - enable_acknowledgment_messages
      description: Persona configuration
      title: Persona
    PersonaUpdateMessageLength:
      type: string
      enum:
        - concise
        - normal
      title: PersonaUpdateMessageLength
    PersonaUpdate:
      type: object
      properties:
        personality:
          type: array
          items:
            type: string
        emoji_usage:
          type: boolean
        allowed_emojis:
          type: string
        default_timezone:
          type: string
        company_description:
          type:
            - string
            - 'null'
        community_guidelines_url:
          type:
            - string
            - 'null'
        message_length:
          $ref: '#/components/schemas/PersonaUpdateMessageLength'
        ask_for_more_help:
          type: boolean
        no_customer_pi:
          type: boolean
        no_competitors:
          type: boolean
        competitor_names:
          type:
            - string
            - 'null'
        enable_acknowledgment_messages:
          type: boolean
      description: Partial persona update. All fields optional.
      title: PersonaUpdate
    VariableSummary:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the Variable
        name:
          type: string
          description: The name of the Variable
      required:
        - id
        - name
      description: |
        A Variable as returned by the list and get endpoints. Carries the
        Variable's id, used to reference it elsewhere, and its name.
      title: VariableSummary
    variables_list_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/VariableSummary'
      required:
        - data
      title: variables_list_Response_200
    CustomInstruction:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the custom instruction
        title:
          type: string
          maxLength: 150
          description: Display name for the custom instruction (unique per Agent)
        text:
          type: string
          maxLength: 300
          description: The instruction content — the rule the Agent should follow
        enabled:
          type: boolean
          default: false
          description: Whether the instruction is enabled. False means inactive.
        notes:
          type:
            - string
            - 'null'
          description: Internal notes about this instruction (not shown to the Agent)
        availability_rules:
          type:
            - string
            - 'null'
          description: >-
            Availability rule gating which end users this instruction applies to, as a rule-expression string with
            `v("<variable_name>")` variable lookups. `null` when no rule is set.
      required:
        - id
        - title
        - text
        - enabled
      description: A custom instruction — system-level behavioral guidance for the AI Agent
      title: CustomInstruction
    CustomInstructionListMeta:
      type: object
      properties:
        next_page_url:
          type:
            - string
            - 'null'
          description: >-
            URL for the next page of results, or null on the last/empty page. Replay it unchanged to fetch the next
            page.
      description: Pagination metadata
      title: CustomInstructionListMeta
    CustomInstructionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomInstruction'
          description: The list of custom instructions
        meta:
          $ref: '#/components/schemas/CustomInstructionListMeta'
          description: Pagination metadata
      required:
        - data
        - meta
      title: CustomInstructionList
    CustomInstructionCreate:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 150
          description: Display name for the custom instruction (unique per Agent)
        text:
          type: string
          minLength: 1
          maxLength: 300
          description: The instruction content — the rule the Agent should follow
        enabled:
          type: boolean
          default: false
          description: Whether the instruction is enabled. False means inactive.
        notes:
          type: string
          description: Internal notes about this instruction (not shown to the Agent)
        availability_rules:
          type:
            - string
            - 'null'
          description: >-
            Optional availability rule as a rule-expression string with `v("<variable_name>")` lookups. Omit or send
            `null` for no rule. A rule that references an unknown variable, or that is malformed or uses an unsupported
            operator, is rejected with 400.
      required:
        - title
        - text
      description: Fields for creating a custom instruction
      title: CustomInstructionCreate
    Custom Instructions_deleteCustomInstruction_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: Custom Instructions_deleteCustomInstruction_Response_204
    CustomInstructionUpdate:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 150
          description: Display name for the custom instruction (unique per Agent)
        text:
          type: string
          minLength: 1
          maxLength: 300
          description: The instruction content — the rule the Agent should follow
        enabled:
          type: boolean
          description: Whether the instruction is enabled. False means inactive.
        notes:
          type: string
          description: >-
            Internal notes about this instruction (not shown to the Agent). Send an empty string to blank it; omit it to
            leave the existing notes unchanged.
        availability_rules:
          type:
            - string
            - 'null'
          description: >-
            Optional availability rule as a rule-expression string with `v("<variable_name>")` lookups. Send a non-empty
            string to set or replace it, `null` to clear it, or omit to leave it unchanged. A rule that references an
            unknown variable, or that is malformed or uses an unsupported operator, is rejected with 400.
      description: >-
        Fields for updating a custom instruction. Only the fields provided are changed; omitted fields are left as they
        are.
      title: CustomInstructionUpdate
    V2ToolsGetParametersType:
      type: string
      enum:
        - api
        - code
      title: V2ToolsGetParametersType
    ToolType:
      type: string
      enum:
        - api
        - code
      description: Which kind of tool this is, and which implementation key is present
      title: ToolType
    ToolInput:
      type: object
      properties:
        name:
          type: string
          description: The input's name, unique within the tool
        type:
          type:
            - string
            - 'null'
          description: The input's data type. `null` when the tool declares no type for it.
        description:
          type: string
          description: What the input is for, as shown to the model
        required:
          type:
            - boolean
            - 'null'
          description: Whether the tool requires this input. `null` for `api` and `code` tools, which do not model optionality.
      required:
        - name
        - type
        - description
        - required
      description: One input the tool declares.
      title: ToolInput
    ToolOutputSource:
      type: string
      enum:
        - body
        - status_code
      description: Which part of the HTTP response the value is read from. `api` tools only; `null` for every other type.
      title: ToolOutputSource
    ToolOutputVariable:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: The variable's id
      required:
        - id
      description: >-
        The variable the value is saved to, referenced by `id`. `null` when the output is not persisted, or when its
        variable no longer exists.
      title: ToolOutputVariable
    ToolOutput:
      type: object
      properties:
        name:
          type: string
          description: The output's name, unique within the tool
        key:
          type:
            - string
            - 'null'
          description: Path to the value in the tool's result. `null` when the tool does not address its outputs by path.
        source:
          oneOf:
            - $ref: '#/components/schemas/ToolOutputSource'
            - type: 'null'
          description: Which part of the HTTP response the value is read from. `api` tools only; `null` for every other type.
        is_visible_to_llm:
          type: boolean
          description: Whether the model can read this output
        save_as_variable:
          type: boolean
          description: Whether the value is persisted to a variable
        variable:
          oneOf:
            - $ref: '#/components/schemas/ToolOutputVariable'
            - type: 'null'
          description: >-
            The variable the value is saved to, referenced by `id`. `null` when the output is not persisted, or when its
            variable no longer exists.
      required:
        - name
        - key
        - source
        - is_visible_to_llm
        - save_as_variable
        - variable
      description: One value the tool returns
      title: ToolOutput
    ToolApiRequestMethod:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
      description: The HTTP method
      title: ToolApiRequestMethod
    ToolApiRequestContentType:
      type: string
      enum:
        - json
        - xml
        - url_encoded
      description: How the request body is encoded
      title: ToolApiRequestContentType
    ToolHeader:
      type: object
      properties:
        name:
          type: string
          description: The header's name
        value:
          type: string
          description: The header's value. Variable references appear in the `{var:<name>|<default>}` form.
      required:
        - name
        - value
      title: ToolHeader
    ToolApiRequest:
      type: object
      properties:
        method:
          $ref: '#/components/schemas/ToolApiRequestMethod'
          description: The HTTP method
        content_type:
          $ref: '#/components/schemas/ToolApiRequestContentType'
          description: How the request body is encoded
        body:
          type: string
          description: The request body template. Variable references appear in the `{var:<name>|<default>}` form.
        headers:
          type: array
          items:
            $ref: '#/components/schemas/ToolHeader'
          description: Request headers. `Authorization` is never returned, whether or not the tool sends one.
      required:
        - method
        - content_type
        - body
        - headers
      description: The HTTP request shape for an `api` tool, nested under `api.request`.
      title: ToolApiRequest
    ToolApiBody:
      type: object
      properties:
        url:
          type: string
          description: The request URL. Variable references appear in the `{var:<name>|<default>}` form.
        request:
          $ref: '#/components/schemas/ToolApiRequest'
      required:
        - url
        - request
      description: How an `api` tool calls its HTTP endpoint
      title: ToolApiBody
    ToolEnvVarSource:
      type: string
      enum:
        - literal
        - variable
        - secret
        - sensitive_value
      description: Where the value comes from. One of `literal`, `variable`, `secret`, or `sensitive_value`.
      title: ToolEnvVarSource
    ToolEnvVar:
      type: object
      properties:
        key:
          type: string
          description: The environment variable's name
        source:
          $ref: '#/components/schemas/ToolEnvVarSource'
          description: Where the value comes from. One of `literal`, `variable`, `secret`, or `sensitive_value`.
        value:
          type: string
          description: >-
            The literal value, or the id of the variable or secret, depending on `source`. When `source` is
            `sensitive_value`, this is write-only: it is stored encrypted and always read back empty. On PATCH,
            submitting it empty leaves the stored secret unchanged. Remove the row to clear it. On POST, empty stores an
            empty secret. A GET-then-POST copy does not copy the stored secret.
      required:
        - key
        - source
        - value
      title: ToolEnvVar
    ToolCodeBody:
      type: object
      properties:
        source_code:
          type: string
          description: The tool's Python source
        environment:
          type: array
          items:
            $ref: '#/components/schemas/ToolEnvVar'
          description: Environment variables exposed to the sandbox
      required:
        - source_code
        - environment
      description: The sandboxed Python a `code` tool runs
      title: ToolCodeBody
    Tool:
      type: object
      properties:
        id:
          type: string
          description: The tool's id
        type:
          $ref: '#/components/schemas/ToolType'
          description: Which kind of tool this is, and which implementation key is present
        name:
          type: string
          description: The tool's name, as the model sees it
        description:
          type: string
          description: What the tool does, as the model sees it
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/ToolInput'
          description: The inputs the tool declares
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/ToolOutput'
          description: The values the tool returns.
        enabled:
          type: boolean
          description: Whether the tool is available to the Agent at all
        direct_use:
          type:
            - boolean
            - 'null'
          description: Whether the Agent may call this tool on its own, rather than only as a step inside a process.
        availability:
          oneOf:
            - $ref: '#/components/schemas/AvailabilityRule'
            - type: 'null'
          description: The rule that gates when the tool is offered. `null` when the tool is always available.
        api:
          $ref: '#/components/schemas/ToolApiBody'
        code:
          $ref: '#/components/schemas/ToolCodeBody'
      required:
        - id
        - type
        - name
        - description
        - inputs
        - outputs
        - enabled
        - direct_use
        - availability
      description: >-
        A tool the AI Agent can call. The contract the model sees and the controls that gate it are shared across types;
        the implementation is nested under the key matching `type`. List items omit the type body (`api` / `code`).
      title: Tool
    ToolList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
          description: The page of tools
        meta:
          $ref: '#/components/schemas/PaginationMetadata'
      required:
        - data
        - meta
      title: ToolList
    ToolCreateType:
      type: string
      enum:
        - api
        - code
      title: ToolCreateType
    ToolInputCreate:
      type: object
      properties:
        name:
          type: string
        type:
          type:
            - string
            - 'null'
        description:
          type: string
        required:
          type:
            - boolean
            - 'null'
          description: >-
            Ignored on write. GET always emits this field; api and code tools send `null`. Accepted so a GET body can be
            PATCHed back.
      required:
        - name
      description: >-
        An input on create or PATCH. `required` is ignored on write; GET always emits it (`null` for api and code
        tools).
      title: ToolInputCreate
    ToolOutputCreateSource:
      type: string
      enum:
        - body
        - status_code
      title: ToolOutputCreateSource
    AvailabilityRuleVariableRef:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: The variable's id
      required:
        - id
      description: Reference to a variable by its id
      title: AvailabilityRuleVariableRef
    ToolOutputCreate:
      type: object
      properties:
        name:
          type: string
        key:
          type:
            - string
            - 'null'
        source:
          oneOf:
            - $ref: '#/components/schemas/ToolOutputCreateSource'
            - type: 'null'
        is_visible_to_llm:
          type: boolean
        save_as_variable:
          type: boolean
        variable:
          oneOf:
            - $ref: '#/components/schemas/AvailabilityRuleVariableRef'
            - type: 'null'
      required:
        - name
      description: An output on create. Only `name` is required.
      title: ToolOutputCreate
    ToolApiRequestCreateMethod:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
      title: ToolApiRequestCreateMethod
    ToolApiRequestCreateContentType:
      type: string
      enum:
        - json
        - xml
        - url_encoded
      title: ToolApiRequestCreateContentType
    ToolApiRequestCreate:
      type: object
      properties:
        method:
          $ref: '#/components/schemas/ToolApiRequestCreateMethod'
        content_type:
          $ref: '#/components/schemas/ToolApiRequestCreateContentType'
        body:
          type: string
        headers:
          type: array
          items:
            $ref: '#/components/schemas/ToolHeader'
      description: >-
        HTTP request on create. `method` and `content_type` default in the handler; `body` and `headers` default to
        empty.
      title: ToolApiRequestCreate
    ToolApiBodyCreate:
      type: object
      properties:
        url:
          type: string
        request:
          $ref: '#/components/schemas/ToolApiRequestCreate'
      required:
        - url
      description: How an `api` tool calls its HTTP endpoint, on create
      title: ToolApiBodyCreate
    ToolCodeBodyCreate:
      type: object
      properties:
        source_code:
          type: string
        environment:
          type: array
          items:
            $ref: '#/components/schemas/ToolEnvVar'
      required:
        - source_code
      description: The sandboxed Python a `code` tool runs, on create
      title: ToolCodeBodyCreate
    ToolCreate:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ToolCreateType'
        name:
          type: string
        description:
          type: string
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/ToolInputCreate'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/ToolOutputCreate'
        enabled:
          type: boolean
          default: true
        direct_use:
          type:
            - boolean
            - 'null'
        availability:
          oneOf:
            - $ref: '#/components/schemas/AvailabilityRule'
            - type: 'null'
        api:
          $ref: '#/components/schemas/ToolApiBodyCreate'
        code:
          $ref: '#/components/schemas/ToolCodeBodyCreate'
      required:
        - type
        - name
        - description
      description: >-
        Body for `POST /v2/tools`. Create-side envelope — no `id`, and nested schemas require only what the write path
        consumes. `api` and `code` create a tool.
      title: ToolCreate
    tools_delete_Response_204:
      type: object
      properties: {}
      description: Empty response body
      title: tools_delete_Response_204
    ToolPatchType:
      type: string
      enum:
        - api
        - code
      description: If sent, must match the existing tool. Changing type is not supported.
      title: ToolPatchType
    ToolApiRequestPatchMethod:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
      title: ToolApiRequestPatchMethod
    ToolApiRequestPatchContentType:
      type: string
      enum:
        - json
        - xml
        - url_encoded
      title: ToolApiRequestPatchContentType
    ToolApiRequestPatch:
      type: object
      properties:
        method:
          $ref: '#/components/schemas/ToolApiRequestPatchMethod'
        content_type:
          $ref: '#/components/schemas/ToolApiRequestPatchContentType'
        body:
          type: string
        headers:
          type: array
          items:
            $ref: '#/components/schemas/ToolHeader'
      description: Partial HTTP request on PATCH. Omitted keys are preserved; there are no create-time defaults.
      title: ToolApiRequestPatch
    ToolApiBodyPatch:
      type: object
      properties:
        url:
          type: string
        request:
          $ref: '#/components/schemas/ToolApiRequestPatch'
      description: Partial `api` implementation. Omitted keys are preserved.
      title: ToolApiBodyPatch
    ToolCodeBodyPatch:
      type: object
      properties:
        source_code:
          type: string
        environment:
          type: array
          items:
            $ref: '#/components/schemas/ToolEnvVar'
      description: Partial `code` implementation. Omitted keys are preserved.
      title: ToolCodeBodyPatch
    ToolPatch:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ToolPatchType'
          description: If sent, must match the existing tool. Changing type is not supported.
        name:
          type: string
        description:
          type: string
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/ToolInputCreate'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/ToolOutputCreate'
        enabled:
          type: boolean
        direct_use:
          type: boolean
        availability:
          oneOf:
            - $ref: '#/components/schemas/AvailabilityRule'
            - type: 'null'
        api:
          $ref: '#/components/schemas/ToolApiBodyPatch'
        code:
          $ref: '#/components/schemas/ToolCodeBodyPatch'
      description: >-
        Body for `PATCH /v2/tools/{tool_id}`. Every field is optional. Omitted fields are preserved. Arrays replace in
        full when present. `availability: null` detaches the rule.
      title: ToolPatch
    EndUserCreatedWebhookPayloadData:
      type: object
      properties:
        end_user_id:
          type: string
          description: The unique Ada-generated id for the end user
        external_id:
          type:
            - string
            - 'null'
          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).
        profile:
          $ref: '#/components/schemas/EndUserProfile'
          description: The end user's profile information
        created_at:
          type: string
          description: The date and time the end user was created
        updated_at:
          type: string
          description: The date and time the end user was updated
      description: The webhook event data
      title: EndUserCreatedWebhookPayloadData
    EndUserCreatedWebhookPayload:
      type: object
      properties:
        type:
          type: string
          description: The webhook event type description
        timestamp:
          type: string
          description: >-
            The timestamp for when the event was generated. Uses millisecond precision to help with event ordering
            needs.
        data:
          $ref: '#/components/schemas/EndUserCreatedWebhookPayloadData'
          description: The webhook event data
        tags:
          type: array
          items:
            type: string
          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.
      title: EndUserCreatedWebhookPayload
    EndUserUpdatedWebhookPayloadData:
      type: object
      properties:
        end_user_id:
          type: string
          description: The unique Ada-generated id for the end user
        external_id:
          type:
            - string
            - 'null'
          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).
        profile:
          $ref: '#/components/schemas/EndUserProfile'
          description: The end user's profile information
        created_at:
          type: string
          description: The date and time the end user was created
        updated_at:
          type: string
          description: The date and time the end user was updated
      description: The webhook event data
      title: EndUserUpdatedWebhookPayloadData
    EndUserUpdatedWebhookPayload:
      type: object
      properties:
        type:
          type: string
          description: The webhook event type description
        timestamp:
          type: string
          description: >-
            The timestamp for when the event was generated. Uses millisecond precision to help with event ordering
            needs.
        data:
          $ref: '#/components/schemas/EndUserUpdatedWebhookPayloadData'
          description: The webhook event data
        tags:
          type: array
          items:
            type: string
          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.
      title: EndUserUpdatedWebhookPayload
    AuditLogWebhookEventDataActivity:
      type: string
      enum:
        - created
        - updated
        - deleted
        - executed
        - invited
        - activated
        - deactivated
      description: What happened to the entity
      title: AuditLogWebhookEventDataActivity
    AuditLogWebhookEventData:
      type: object
      properties:
        id:
          type: string
          description: Globally unique audit event id
        timestamp:
          type: string
          format: date-time
          description: When the configuration change occurred (ISO 8601, UTC, millisecond precision)
        actor_email:
          type: string
          description: >-
            Email of the actor (the user, or the owner of a dashboard-created Platform API key); empty for system and
            service-token actors.
        actor_name:
          type: string
          description: Display name of the actor; empty when unavailable
        actor_user_id:
          type: string
          description: >-
            User id of the actor. For an API key, the id of the user who created the key. Empty for system and
            service-token actors.
        entity_type:
          type: string
          description: The type of entity that was changed
        entity_id:
          type: string
          description: The id of the entity that was changed
        entity_name:
          type: string
          description: Human-readable name of the changed entity
        activity:
          $ref: '#/components/schemas/AuditLogWebhookEventDataActivity'
          description: What happened to the entity
        interface:
          type: string
          description: Where the change originated, such as `dashboard`, `api`, `mcp`, `cli`, `import`, `export`, or `system`.
        context_ip:
          type: string
          description: Source IP address of the request that made the change
        context_user_agent:
          type: string
          description: User agent string of the request that made the change
        api_key_name:
          type: string
          description: Name of the API key used, when the change was made by a dashboard-created Platform API key; empty otherwise.
      required:
        - id
        - timestamp
        - entity_type
        - entity_id
        - activity
      description: >-
        A configuration change recorded by the Audit log, delivered as the `data` field of a `v1.audit_log.emitted`
        webhook.
      title: AuditLogWebhookEventData
    AuditLogWebhookPayload:
      type: object
      properties:
        type:
          type: string
          description: >-
            The webhook event type. Audit log events use `v1.audit_log.emitted`; the `data.activity` field identifies
            what changed.
        timestamp:
          type: string
          format: date-time
          description: When the event was generated (millisecond precision, to help with event ordering)
        data:
          $ref: '#/components/schemas/AuditLogWebhookEventData'
          description: The Audit log event data
        tags:
          type: array
          items:
            type: string
          description: >-
            Tags for filtering webhook events in the Ada dashboard. Includes `entity_type`, `activity`, and `entity_id`
            by default. Ada may add additional tags at any time.
      required:
        - type
        - timestamp
        - data
      description: The body delivered to your endpoint for a `v1.audit_log.emitted` event
      title: AuditLogWebhookPayload
    ConversationCreatedWebhookPayloadType:
      type: string
      enum:
        - v1.conversation.created
      description: The webhook event type
      title: ConversationCreatedWebhookPayloadType
    ConversationCreatedWebhookPayloadDataMetadata:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
          format: double
      title: ConversationCreatedWebhookPayloadDataMetadata
    ConversationCreatedWebhookPayloadData:
      type: object
      properties:
        conversation_id:
          type: string
          description: The ID of the conversation
        channel_id:
          type: string
          description: The ID of the channel
        created_at:
          type: string
          description: The date and time the conversation was created
        end_user_id:
          type: string
          description: The ID of the end user associated with the conversation
        metadata:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ConversationCreatedWebhookPayloadDataMetadata'
          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)
        ai_agent_domain:
          type: string
          description: The API domain of the AI Agent environment this webhook event is emitted from
      description: The webhook event data
      title: ConversationCreatedWebhookPayloadData
    ConversationCreatedWebhookPayload:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ConversationCreatedWebhookPayloadType'
          description: The webhook event type
        timestamp:
          type: string
          description: The timestamp for when the event was generated (uses millisecond precision to help with event ordering)
        data:
          $ref: '#/components/schemas/ConversationCreatedWebhookPayloadData'
          description: The webhook event data
      title: ConversationCreatedWebhookPayload
    ConversationMessageWebhookPayloadType:
      type: string
      enum:
        - v1.conversation.message
      description: The webhook event type
      title: ConversationMessageWebhookPayloadType
    ConversationMessageWebhookNativeChannelType:
      type: string
      enum:
        - native
      description: The type of the channel
      title: ConversationMessageWebhookNativeChannelType
    ConversationMessageWebhookCustomChannelType:
      type: string
      enum:
        - custom
      description: The type of the channel
      title: ConversationMessageWebhookCustomChannelType
    ConversationMessageWebhookCustomChannelMetadata:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
      title: ConversationMessageWebhookCustomChannelMetadata
    ConversationMessageWebhookChannel:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/ConversationMessageWebhookNativeChannelType'
              description: The type of the channel
            id:
              type: string
              description: The channel ID
            name:
              type: string
              description: The name of the channel
            description:
              type: string
              description: A description of the channel
            modality:
              $ref: '#/components/schemas/BaseChannelModality'
              description: The modality of the channel
            capabilities:
              $ref: '#/components/schemas/BaseChannelCapabilities'
              description: >-
                What the channel's surface can render. The AI Agent tailors replies to the declared capabilities.
                Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the
                surface.
          required:
            - type
            - name
            - description
            - modality
            - id
          description: native variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/ConversationMessageWebhookCustomChannelType'
              description: The type of the channel
            id:
              type: string
              format: id
              description: The channel ID
            name:
              type: string
              description: The name of the channel
            description:
              type: string
              description: A description of the channel
            modality:
              $ref: '#/components/schemas/BaseChannelModality'
              description: The modality of the channel
            capabilities:
              $ref: '#/components/schemas/BaseChannelCapabilities'
              description: >-
                What the channel's surface can render. The AI Agent tailors replies to the declared capabilities.
                Omitted fields default to false. Read-only on native channels, whose capabilities are fixed by the
                surface.
            metadata:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/ConversationMessageWebhookCustomChannelMetadata'
              description: |
                A dictionary of key/value pairs assigned to the channel. Metadata may not exceed 4KB total
                - keys: string
                - values: string, boolean, or integer
            created_at:
              type: string
              format: date-time
              description: The date and time the channel was created
          required:
            - type
            - name
            - description
            - modality
            - id
          description: custom variant
      discriminator:
        propertyName: type
      title: ConversationMessageWebhookChannel
    ConversationMessageWebhookPayloadDataAuthorRole:
      type: string
      enum:
        - end_user
        - ai_agent
        - human_agent
      description: The author's role
      title: ConversationMessageWebhookPayloadDataAuthorRole
    ConversationMessageWebhookPayloadDataAuthor:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
          description: The ID of the user that will be participating in the conversation
        role:
          $ref: '#/components/schemas/ConversationMessageWebhookPayloadDataAuthorRole'
          description: The author's role
        avatar:
          type:
            - string
            - 'null'
          description: The URL of the author's avatar
        display_name:
          type:
            - string
            - 'null'
          description: The author's display name
      description: Information about the message author
      title: ConversationMessageWebhookPayloadDataAuthor
    ConversationMessageWebhookPayloadDataContent:
      oneOf:
        - $ref: '#/components/schemas/TextContent'
        - $ref: '#/components/schemas/LinkContent'
        - $ref: '#/components/schemas/FileContent'
      title: ConversationMessageWebhookPayloadDataContent
    ConversationMessageWebhookPayloadData:
      type: object
      properties:
        message_id:
          type: string
          description: The ID of the message that triggered the webhook event
        conversation_id:
          type: string
          description: The ID of the conversation that contains the message
        end_user_id:
          type: string
          description: The ID of the end user associated with the conversation
        handoff_integration:
          type:
            - string
            - 'null'
          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.
        channel:
          $ref: '#/components/schemas/ConversationMessageWebhookChannel'
          description: The channel that the message was sent on
        created_at:
          type: string
          description: The date and time the message was created
        author:
          $ref: '#/components/schemas/ConversationMessageWebhookPayloadDataAuthor'
          description: Information about the message author
        content:
          $ref: '#/components/schemas/ConversationMessageWebhookPayloadDataContent'
        ai_agent_domain:
          type: string
          description: The API domain of the AI Agent environment this webhook event is emitted from
      description: The webhook event data
      title: ConversationMessageWebhookPayloadData
    ConversationMessageWebhookPayload:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ConversationMessageWebhookPayloadType'
          description: The webhook event type
        timestamp:
          type: string
          description: The timestamp for when the event was generated, uses millisecond precision to help with event ordering needs
        data:
          $ref: '#/components/schemas/ConversationMessageWebhookPayloadData'
          description: The webhook event data
      title: ConversationMessageWebhookPayload
    ConversationEndedWebhookPayloadType:
      type: string
      enum:
        - v1.conversation.ended
      description: The webhook event type
      title: ConversationEndedWebhookPayloadType
    ConversationEndedWebhookPayloadDataEndedByRole:
      type: string
      enum:
        - end_user
        - system
        - human_agent
      description: The role that ended the conversation
      title: ConversationEndedWebhookPayloadDataEndedByRole
    ConversationEndedWebhookPayloadDataEndedBy:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
          description: The ID of the user that ended the conversation
        role:
          $ref: '#/components/schemas/ConversationEndedWebhookPayloadDataEndedByRole'
          description: The role that ended the conversation
      title: ConversationEndedWebhookPayloadDataEndedBy
    ConversationEndedWebhookPayloadDataMetadata:
      oneOf:
        - type: string
        - type: boolean
        - type: integer
        - type: number
          format: double
      title: ConversationEndedWebhookPayloadDataMetadata
    ConversationEndedWebhookPayloadData:
      type: object
      properties:
        conversation_id:
          type: string
          description: The ID of the conversation that was ended
        channel_id:
          type: string
          description: The ID of the channel
        end_user_id:
          type: string
          description: The ID of the end user associated with the conversation
        created_at:
          type: string
          description: The date and time the conversation was created
        updated_at:
          type: string
          description: The date and time the conversation was last updated
        ended_by:
          $ref: '#/components/schemas/ConversationEndedWebhookPayloadDataEndedBy'
        metadata:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ConversationEndedWebhookPayloadDataMetadata'
          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)
        ai_agent_domain:
          type: string
          description: The API domain of the AI Agent environment this webhook event is emitted from
      description: The webhook event data
      title: ConversationEndedWebhookPayloadData
    ConversationEndedWebhookPayload:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ConversationEndedWebhookPayloadType'
          description: The webhook event type
        timestamp:
          type: string
          description: The timestamp for when the event was generated, uses millisecond precision to help with event ordering
        data:
          $ref: '#/components/schemas/ConversationEndedWebhookPayloadData'
          description: The webhook event data
      title: ConversationEndedWebhookPayload
    ConversationHandoffEndedWebhookPayloadType:
      type: string
      enum:
        - v1.conversation.handoff.ended
      description: The webhook event type
      title: ConversationHandoffEndedWebhookPayloadType
    ConversationHandoffEndedWebhookPayloadData:
      type: object
      properties:
        conversation_id:
          type: string
          description: The ID of the conversation where the handoff was ended
        end_user_id:
          type: string
          description: The ID of the end user associated with the conversation
        handoff_integration:
          type: string
          description: The handoff integration that was ended
        ai_agent_domain:
          type: string
          description: The API domain of the AI Agent environment this webhook event is emitted from
      required:
        - conversation_id
        - end_user_id
        - handoff_integration
        - ai_agent_domain
      description: The webhook event data
      title: ConversationHandoffEndedWebhookPayloadData
    ConversationHandoffEndedWebhookPayload:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ConversationHandoffEndedWebhookPayloadType'
          description: The webhook event type
        timestamp:
          type: string
          description: The timestamp for when the event was generated, uses millisecond precision to help with event ordering
        data:
          $ref: '#/components/schemas/ConversationHandoffEndedWebhookPayloadData'
          description: The webhook event data
      title: ConversationHandoffEndedWebhookPayload
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
