Coveo Agent Orchestration API API

openapi: 3.0.1
info:
  title: Coveo Activity Activities Agent Orchestration API API
  description: API for Coveo Platform
  termsOfService: https://www.coveo.com/en/support/terms-agreements
  contact:
    name: Coveo
    url: https://connect.coveo.com/s/discussions
  version: 1.0.0
servers:
- url: https://platform.cloud.coveo.com
  description: Coveo public API endpoint
security:
- oauth2:
  - full
tags:
- name: Agent Orchestration API
paths:
  /api/preview/organizations/{organizationId}/agents/{agentId}/follow-up:
    post:
      tags:
      - Agent Orchestration API
      summary: Generates an Answer to the Follow-Up Question for the Given Configuration
      operationId: followUp
      parameters:
      - name: organizationId
        in: path
        description: The organization id
        required: true
        schema:
          type: string
          description: Organization identifier
      - name: agentId
        in: path
        description: The agent id
        required: true
        schema:
          type: string
          description: The agent id
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompositeModelFollowUpPayload_Request'
        required: true
      responses:
        '200':
          description: OK
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SseEmitter_Response'
      x-pretty-name: followUp
      x-ui-operation-id: /api/preview/organizations/paramId/agents/paramId/follow-up_post
  /api/preview/organizations/{organizationId}/agents/{agentId}/answer:
    post:
      tags:
      - Agent Orchestration API
      summary: Generates an Answer for the Given Configuration
      operationId: answer
      parameters:
      - name: organizationId
        in: path
        description: The organization id
        required: true
        schema:
          type: string
          description: Organization identifier
      - name: agentId
        in: path
        description: The agent id
        required: true
        schema:
          type: string
          description: The agent id
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompositeModelAnswerPayload_Request'
        required: true
      responses:
        '200':
          description: OK
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SseEmitter_Response'
      x-pretty-name: answer
      x-ui-operation-id: /api/preview/organizations/paramId/agents/paramId/answer_post
components:
  schemas:
    CompositeModelAnswerPayload_Request:
      required:
      - q
      type: object
      properties:
        q:
          maxLength: 50000
          minLength: 0
          type: string
          description: The user question.
        searchHub:
          maxLength: 255
          minLength: 0
          type: string
          description: The search hub.
        pipeline:
          maxLength: 50
          minLength: 0
          type: string
          description: The query pipeline name.
        facets:
          type: array
          description: The list of facets.
          items:
            $ref: '#/components/schemas/FacetRequest_Request'
        locale:
          maxLength: 255
          minLength: 2
          type: string
          description: The user locale preferences.
        citationsFieldToInclude:
          maxItems: 255
          minItems: 0
          type: array
          description: The citation fields to include in the response.
          items:
            maxLength: 255
            minLength: 0
            type: string
            description: The citation fields to include in the response.
        recordDebugSession:
          type: boolean
          description: Optional. Whether to record debug session data for this conversation. Defaults to false when omitted.
          default: false
        context:
          type: object
        aq:
          maxLength: 100000
          minLength: 0
          type: string
          description: The advanced query expression.
          nullable: true
        cq:
          maxLength: 100000
          minLength: 0
          type: string
          description: The constant query expression.
          nullable: true
        referrer:
          type: string
          description: The URL of the referrer page.
          nullable: true
        tab:
          maxLength: 1024
          minLength: 0
          type: string
          description: The name or identifier of the search tab.
          nullable: true
        analytics:
          $ref: '#/components/schemas/Analytics_Request'
      description: Payload for getting an answer from an agent.
    NumericalRangeFacetRequest_Request:
      type: object
      properties:
        field:
          maxLength: 254
          minLength: 1
          pattern: ^[a-z][a-zA-Z0-9_]*$
          type: string
          description: The name of the field on which to base the facet request.
          example: author
        facetId:
          maxLength: 60
          minLength: 1
          pattern: ^[A-Za-z0-9_@-]*$
          type: string
          description: The unique identifier of the facet in the search interface.
          example: author-1
        type:
          type: string
          description: The kind of values to request for the facet.
          default: specific
          enum:
          - specific
          - dateRange
          - numericalRange
          - hierarchical
        filterFacetCount:
          type: boolean
          description: Whether to exclude folded result parents when estimating the result count for each facet value.
        injectionDepth:
          type: integer
          description: The maximum number of items to scan for facet values.
          format: int32
        isFieldExpanded:
          type: boolean
          description: Whether to make this facet request in the context of requesting more facet values.
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting values.
        resultsMustMatch:
          type: string
          description: Specifies how a result must match the selected values.
          enum:
          - atLeastOneValue
          - allValues
        numberOfValues:
          type: integer
          description: The maximum number of facet values to fetch.
          format: int32
        freezeCurrentValues:
          type: boolean
          description: Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.
        generateAutomaticRanges:
          type: boolean
          description: Whether to automatically generate range values for this facet.
        sortCriteria:
          type: string
          description: The criterion to use for sorting returned facet values.
          enum:
          - ascending
          - descending
          - occurrences
          - ascending
          - descending
          - occurrences
        currentValues:
          type: array
          description: The values displayed by the facet in the search interface at the moment of the request.
          items:
            $ref: '#/components/schemas/NumericalRangeFacetValue_Request'
        rangeAlgorithm:
          type: string
          description: Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.
          enum:
          - equiprobable
          - even
      description: Request facet values representing ranges of numbers.
    SpecificFacetValue_Request:
      type: object
      properties:
        state:
          type: string
          description: The current facet value state in the search interface.
          enum:
          - idle
          - selected
          - excluded
        previousState:
          type: string
          description: The previous facet value state in the search interface.
          enum:
          - idle
          - selected
          - excluded
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting the facet value.
        value:
          type: string
          description: The facet value name.
          example: Alice Smith
      description: A specific facet value.
    FacetRequest_Request:
      required:
      - type
      type: object
      properties:
        type:
          type: string
      description: A facet request. The type property determines the kind of facet values to request.
      discriminator:
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/SpecificFacetRequest_Request'
      - $ref: '#/components/schemas/HierarchicalFacetRequest_Request'
      - $ref: '#/components/schemas/DateRangeFacetRequest_Request'
      - $ref: '#/components/schemas/NumericalRangeFacetRequest_Request'
    DateRangeFacetValue_Request:
      type: object
      properties:
        state:
          type: string
          description: The current facet value state in the search interface.
          enum:
          - idle
          - selected
          - excluded
        previousState:
          type: string
          description: The previous facet value state in the search interface.
          enum:
          - idle
          - selected
          - excluded
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting the facet value.
        endInclusive:
          type: boolean
          description: Whether to include the end value in the range.
        start:
          pattern: ^\d{4}/\d{2}/\d{2}@\d{1,2}:\d{2}:\d{2}$
          type: string
          description: The value to start the range at.
          example: 2019/01/01@00:00:00
        end:
          pattern: ^\d{4}/\d{2}/\d{2}@\d{1,2}:\d{2}:\d{2}$
          type: string
          description: The value to end the range at. Must be later than the start value.
          example: 2019/12/31@23:59:59
      description: A date range facet value.
    DateRangeFacetRequest_Request:
      type: object
      properties:
        field:
          maxLength: 254
          minLength: 1
          pattern: ^[a-z][a-zA-Z0-9_]*$
          type: string
          description: The name of the field on which to base the facet request.
          example: author
        facetId:
          maxLength: 60
          minLength: 1
          pattern: ^[A-Za-z0-9_@-]*$
          type: string
          description: The unique identifier of the facet in the search interface.
          example: author-1
        type:
          type: string
          description: The kind of values to request for the facet.
          default: specific
          enum:
          - specific
          - dateRange
          - numericalRange
          - hierarchical
        filterFacetCount:
          type: boolean
          description: Whether to exclude folded result parents when estimating the result count for each facet value.
        injectionDepth:
          type: integer
          description: The maximum number of items to scan for facet values.
          format: int32
        isFieldExpanded:
          type: boolean
          description: Whether to make this facet request in the context of requesting more facet values.
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting values.
        resultsMustMatch:
          type: string
          description: Specifies how a result must match the selected values.
          enum:
          - atLeastOneValue
          - allValues
        numberOfValues:
          type: integer
          description: The maximum number of facet values to fetch.
          format: int32
        freezeCurrentValues:
          type: boolean
          description: Whether to include the currentValues array from the facet request in the values array of the corresponding facet response.
        generateAutomaticRanges:
          type: boolean
          description: Whether to automatically generate range values for this facet.
        sortCriteria:
          type: string
          description: The criterion to use for sorting returned facet values.
          enum:
          - ascending
          - descending
          - occurrences
          - ascending
          - descending
          - occurrences
        currentValues:
          type: array
          description: The values displayed by the facet in the search interface at the moment of the request.
          items:
            $ref: '#/components/schemas/DateRangeFacetValue_Request'
      description: Request facet values representing ranges of dates.
    SseEmitter_Response:
      type: object
      properties:
        timeout:
          type: integer
          format: int64
          nullable: true
    HierarchicalFacetRequest_Request:
      type: object
      properties:
        field:
          maxLength: 254
          minLength: 1
          pattern: ^[a-z][a-zA-Z0-9_]*$
          type: string
          description: The name of the field on which to base the facet request.
          example: author
        facetId:
          maxLength: 60
          minLength: 1
          pattern: ^[A-Za-z0-9_@-]*$
          type: string
          description: The unique identifier of the facet in the search interface.
          example: author-1
        type:
          type: string
          description: The kind of values to request for the facet.
          default: specific
          enum:
          - specific
          - dateRange
          - numericalRange
          - hierarchical
        filterFacetCount:
          type: boolean
          description: Whether to exclude folded result parents when estimating the result count for each facet value.
        injectionDepth:
          type: integer
          description: The maximum number of items to scan for facet values.
          format: int32
        isFieldExpanded:
          type: boolean
          description: Whether to make this facet request in the context of requesting more facet values.
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting values.
        resultsMustMatch:
          type: string
          description: Specifies how a result must match the selected values.
          enum:
          - atLeastOneValue
          - allValues
        basePath:
          type: array
          description: The base path shared by all values for the facet.
          example:
          - Doors
          - Metal
          items:
            type: string
            description: The base path shared by all values for the facet.
            example: '["Doors","Metal"]'
        currentValues:
          type: array
          description: The values displayed by the facet in the search interface at the moment of the request.
          items:
            $ref: '#/components/schemas/HierarchicalFacetValue_Request'
        filterByBasePath:
          type: boolean
          description: Whether to use basePath as a filter for the results.
        numberOfValues:
          type: integer
          description: The maximum number of facet values to fetch.
          format: int32
        delimitingCharacter:
          maxLength: 1
          minLength: 1
          type: string
          description: The character to use to split field values into a hierarchical sequence.
          default: ;
        sortCriteria:
          type: string
          description: The criterion to use for sorting returned facet values. Unsupported values are deserialized to null and treated as if no sort criteria was specified (ignored).
          enum:
          - score
          - ascending
          - descending
          - alphanumeric
          - alphanumericNatural
          - occurrences
          - score
          - ascending
          - descending
          - alphanumeric
          - alphanumericNatural
          - occurrences
      description: Request facet values representing hierarchically structured categories.
    SpecificFacetRequest_Request:
      type: object
      properties:
        field:
          maxLength: 254
          minLength: 1
          pattern: ^[a-z][a-zA-Z0-9_]*$
          type: string
          description: The name of the field on which to base the facet request.
          example: author
        facetId:
          maxLength: 60
          minLength: 1
          pattern: ^[A-Za-z0-9_@-]*$
          type: string
          description: The unique identifier of the facet in the search interface.
          example: author-1
        type:
          type: string
          description: The kind of values to request for the facet.
          default: specific
          enum:
          - specific
          - dateRange
          - numericalRange
          - hierarchical
        filterFacetCount:
          type: boolean
          description: Whether to exclude folded result parents when estimating the result count for each facet value.
        injectionDepth:
          type: integer
          description: The maximum number of items to scan for facet values.
          format: int32
        isFieldExpanded:
          type: boolean
          description: Whether to make this facet request in the context of requesting more facet values.
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting values.
        resultsMustMatch:
          type: string
          description: Specifies how a result must match the selected values.
          enum:
          - atLeastOneValue
          - allValues
        currentValues:
          type: array
          description: The values displayed by the facet in the search interface at the moment of the request.
          items:
            $ref: '#/components/schemas/SpecificFacetValue_Request'
        numberOfValues:
          type: integer
          description: The maximum number of facet values to fetch.
          format: int32
        freezeCurrentValues:
          type: boolean
          description: Whether to include the facet request's currentValues in corresponding facet response's values array.
        sortCriteria:
          type: string
          description: The sort criterion to apply to the returned facet values. Values outside the documented list are accepted but treated as unsupported and deserialized to null, which causes the sort criterion to be omitted and the default behavior to apply.
          enum:
          - score
          - alphanumeric
          - alphanumericNatural
          - occurrences
          - score
          - alphanumeric
          - alphanumericNatural
          - occurrences
        customSort:
          type: array
          description: Facet values that must appear at the top, in this order.
          items:
            type: string
            description: Facet values that must appear at the top, in this order.
      description: Request facet values representing specific values (e.g., Alice Smith, Bob Jones, etc.).
    NumericalRangeFacetValue_Request:
      type: object
      properties:
        state:
          type: string
          description: The current facet value state in the search interface.
          enum:
          - idle
          - selected
          - excluded
        previousState:
          type: string
          description: The previous facet value state in the search interface.
          enum:
          - idle
          - selected
          - excluded
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting the facet value.
        endInclusive:
          type: boolean
          description: Whether to include the end value in the range.
        start:
          type: number
          description: The value to start the range at.
          example: 0
        end:
          type: number
          description: The value to end the range at. Must be greater than the start value.
          example: 100
      description: A numerical range facet value.
    HierarchicalFacetValue_Request:
      type: object
      properties:
        state:
          type: string
          description: The current facet value state in the search interface.
          enum:
          - idle
          - selected
          - excluded
        previousState:
          type: string
          description: The previous facet value state in the search interface.
          enum:
          - idle
          - selected
          - excluded
        preventAutoSelect:
          type: boolean
          description: Whether to prevent Coveo ML from automatically selecting the facet value.
        value:
          maxLength: 512
          minLength: 0
          type: string
          description: This represents a single path segment.
          example: electronics
        children:
          type: array
          description: The children of this hierarchical facet value.
          items:
            $ref: '#/components/schemas/HierarchicalFacetValue_Request'
        retrieveChildren:
          type: boolean
          description: Whether to retrieve the children of this hierarchical facet value. Can only be used on leaf values.
        retrieveCount:
          type: integer
          description: The maximum number of children to retrieve for this hierarchical facet value.
          format: int32
      description: A hierarchical facet value.
    Analytics_Request:
      type: object
      properties:
        capture:
          type: boolean
          description: Whether the search API call should be tracked for analytics and ML purposes.
          nullable: true
        trackingId:
          maxLength: 100
          minLength: 0
          pattern: ^[a-zA-Z0-9_\-\.]+$
          type: string
          description: A value to identify which web property an event is related to.
          nullable: true
        clientId:
          type: string
          description: A GUID representing the current client.
          nullable: true
        documentLocation:
          maxLength: 1024
          minLength: 0
          type: string
          description: The URL of the page that initiated the search.
          nullable: true
        documentReferrer:
          maxLength: 3000
          minLength: 0
          pattern: ^(?:[a-zA-Z][a-zA-Z0-9+.-]*:(?://[^/?#\s]+(?:/[^\s]*)?|(?!//)[^\s]*))?$
          type: string
          description: The URL of the referrer page.
          nullable: true
        pageId:
          maxLength: 36
          minLength: 0
          type: string
          description: An identifier for the current page.
          nullable: true
        userIp:
          maxLength: 45
          minLength: 0
          type: string
          description: The IP address of the end user.
          nullable: true
        clientRequestId:
          maxLength: 255
          minLength: 1
          type: string
          description: A unique identifier for the client request.
          nullable: true
        clientTimestamp:
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}([+-]\d{2}:\d{2}|Z)$
          type: string
          description: ISO 8601 timestamp with milliseconds.
          nullable: true
        userAgent:
          maxLength: 1024
          minLength: 1
          type: string
          description: The user agent string of the client browser.
          nullable: true
        actionCause:
          maxLength: 255
          minLength: 0
          type: string
          description: The cause of the search action.
          nullable: true
        originContext:
          maxLength: 255
          minLength: 1
          type: string
          description: The origin context of the search event.
          nullable: true
        customData:
          type: object
          additionalProperties:
            type: object
            description: Custom key-value data. Max 300 properties.
            nullable: true
          description: Custom key-value data. Max 300 properties.
          nullable: true
        configId:
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          type: string
          description: A lowercase UUID identifying the analytics configuration.
          nullable: true
        source:
          maxItems: 10
          minItems: 0
          type: array
          description: The analytics source identifiers.
          nullable: true
          items:
            pattern: ^.*@.*$
            type: string
            description: The analytics source identifiers.
            nullable: true
        commerce:
          $ref: '#/components/schemas/AnalyticsCommerce_Request'
      description: Analytics parameters to forward to the search API.
      nullable: true
    AnalyticsCommerce_Request:
      required:
      - country
      - currency
      type: object
      properties:
        country:
          pattern: ^[A-Z]{2}$
          type: string
          description: ISO 3166 alpha-2 country code.
          example: US
        currency:
          pattern: ^[A-Z]{3}$
          type: string
          description: ISO 4217 currency code.
          example: USD
      description: Commerce context for the analytics.
      nullable: true
    CompositeModelFollowUpPayload_Request:
      required:
      - conversationId
      - conversationToken
      - q
      type: object
      properties:
        q:
          minLength: 1
          type: string
          description: The query string.
        conversationId:
          type: string
          description: Conversation identifier
        conversationToken:
          minLength: 1
          type: string
          description: The conversation token received from the /answer response.
        analytics:
          $ref: '#/components/schemas/Analytics_Request'
      description: Payload for sending a follow-up question to the agent.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://platform.cloud.coveo.com/oauth/authorize
          tokenUrl: https://platform.cloud.coveo.com/oauth/token
          scopes:
            full: required