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