Coveo Agent Orchestration API API

openapi: 3.2.0
info:
  title: Coveo Knowledge Generative AI Agent Orchestration 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:
    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.
    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.
    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.
    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.
    AnalyticsCommerce_Request:
      required:
      - country
      - currency
      type:
      - object
      - 'null'
      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.
    Analytics_Request:
      type:
      - object
      - 'null'
      properties:
        capture:
          type:
          - boolean
          - 'null'
          description: Whether the search API call should be tracked for analytics and ML purposes.
        trackingId:
          maxLength: 100
          minLength: 0
          pattern: ^[a-zA-Z0-9_\-\.]+$
          type:
          - string
          - 'null'
          description: A value to identify which web property an event is related to.
        clientId:
          type:
          - string
          - 'null'
          description: A GUID representing the current client.
        documentLocation:
          maxLength: 1024
          minLength: 0
          type:
          - string
          - 'null'
          description: The URL of the page that initiated the search.
        documentReferrer:
          maxLength: 3000
          minLength: 0
          pattern: ^(?:[a-zA-Z][a-zA-Z0-9+.-]*:(?://[^/?#\s]+(?:/[^\s]*)?|(?!//)[^\s]*))?$
          type:
          - string
          - 'null'
          description: The URL of the referrer page.
        pageId:
          maxLength: 36
          minLength: 0
          type:
          - string
          - 'null'
          description: An identifier for the current page.
        userIp:
          maxLength: 45
          minLength: 0
          type:
          - string
          - 'null'
          description: The IP address of the end user.
        clientRequestId:
          maxLength: 255
          minLength: 1
          type:
          - string
          - 'null'
          description: A unique identifier for the client request.
        clientTimestamp:
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}([+-]\d{2}:\d{2}|Z)$
          type:
          - string
          - 'null'
          description: ISO 8601 timestamp with milliseconds.
        userAgent:
          maxLength: 1024
          minLength: 1
          type:
          - string
          - 'null'
          description: The user agent string of the client browser.
        actionCause:
          maxLength: 255
          minLength: 0
          type:
          - string
          - 'null'
          description: The cause of the search action.
        originContext:
          maxLength: 255
          minLength: 1
          type:
          - string
          - 'null'
          description: The origin context of the search event.
        customData:
          type:
          - object
          - 'null'
          additionalProperties:
            type:
            - object
            - 'null'
            description: Custom key-value data. Max 300 properties.
          description: Custom key-value data. Max 300 properties.
        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
          - 'null'
          description: A lowercase UUID identifying the analytics configuration.
        source:
          maxItems: 10
          minItems: 0
          type:
          - array
          - 'null'
          description: The analytics source identifiers.
          items:
            pattern: ^.*@.*$
            type:
            - string
            - 'null'
            description: The analytics source identifiers.
        commerce:
          $ref: '#/components/schemas/AnalyticsCommerce_Request'
      description: Analytics parameters to forward to the search API.
    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.).
    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.
    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.
    SseEmitter_Response:
      type: object
      properties:
        timeout:
          type:
          - integer
          - 'null'
          format: int64
    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.
    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.
    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'
    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
          - 'null'
          description: The advanced query expression.
        cq:
          maxLength: 100000
          minLength: 0
          type:
          - string
          - 'null'
          description: The constant query expression.
        referrer:
          type:
          - string
          - 'null'
          description: The URL of the referrer page.
        tab:
          maxLength: 1024
          minLength: 0
          type:
          - string
          - 'null'
          description: The name or identifier of the search tab.
        analytics:
          $ref: '#/components/schemas/Analytics_Request'
      description: Payload for getting an answer from an 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