Answer API (beta)

This is for:

Developer
Important

The Answer API is currently available in beta exclusively for early-access customers. Contact your Customer Success Manager for details on obtaining access.

You can generate answers based on your Coveo index using Relevance Generative Answering (RGA) in interfaces built with one of the Coveo Search UI libraries (Atomic, Headless, Quantic) or in a Coveo builder (Hosted search page builder, In-Product Experience (IPX) builder, Hosted Insight Panel builder). Such interfaces don’t need to call the Answer API directly, as they already have the capability to generate answers using the Coveo Search API.

The Answer API allows you to add an answer generation capability to any custom search interface.

Additionally, leveraging the Answer API in an interface built with a Coveo Search UI library or in a Coveo builder allows you to benefit from the Answer Manager in the Coveo Knowledge Hub. For such a use case, you’ll need to perform additional steps specified down below.

This article focuses on how to directly call the Answer API to generate answers from the Coveo index. It also includes tips on how to enable the Answer API in interfaces built with a Coveo Search UI library or in a Coveo builder.

Limitations

The /generate endpoint doesn’t currently provide debugging information if the Answer API can’t generate an answer. In such a case, the response payload looks like this:

{
  "payloadType": "genqa.endOfStreamType",
  "payload": "{\"answerGenerated\":false}",
  "finishReason": "COMPLETED",
  "errorMessage": null,
  "statusCode": null
}

Prerequisites

  1. Make sure you have the Coveo Knowledge Hub activated in your organization.

    Important

    The Coveo Knowledge Hub is currently available as a beta to early-access customers only. Contact your Customer Success Manager for early access to this feature.

  2. An access token: Either an API key that was created using the Anonymous search template or a search token that grants the Allowed access level on the Execute Queries domain.

Tip

If you’re querying the Answer API from an interface built with a Coveo Search UI library or in a Coveo builder, make sure it’s RGA-enabled.

Activate the Answer API

To start using the Answer API, you must perform the following steps first.

  1. Create an answer configuration in the Coveo Knowledge Hub. When performing this step, copy and save the Configuration ID of the newly created answer configuration as you will need it to make requests to the Answer API.

  2. (optional) Enable rich text formatting to make your answers more readable:

    1. In the query pipeline you configured to handle the queries originating from your search interface, access the Machine Learning tab, and then open the RGA model associated with it.

    2. At the top of the page, click the three dots button and select the Switch to JSON view option.

      A prompt appears asking you to confirm the switch.

    3. Click Switch to JSON view.

    4. In the JSON editor, add the enableContentFormat property to the JSON configuration:

      {
  // ...
  {
    "customQueryParameters":{
      "enableContentFormat": true 1
    }
  }
}
      1 Enables the rich text formatting. For this to take effect, you will need to add the contentFormat parameter in your request payload.

  3. Click Save.

If you’re calling the Answer API from a search page that calls the Search API, or if your interface is built with a Coveo Search UI library or in a Coveo builder:

Additional steps

  1. Associate the created configuration with your RGA-enabled search interface.

  2. As your RGA-enabled search interface is associated with an answer configuration, this might cause the duplication of generative queries per month (GQPM). For more details, see Prevent duplicate GQPM when using the Answer Manager.

    To prevent the duplication, create a condition in RGA association:

    1. In your query pipeline configuration, go to the Machine Learning tab and open the RGA model associated with it.

    2. Click Create a new condition.

    3. In the Add a condition panel, create the following condition: Context[answerAPI] is true.

      Add a condition

  3. Click Add condition.

Request endpoint for generating answers

To generate an answer, send a POST request to the following endpoint. The example below shows how to generate an answer from the Coveo index:

POST https://<MY_ORG_ID>.org.coveo.com/rest/organizations/<MY_ORG_ID>/answer/v1/configs/<CONFIG_ID>/generate HTTP/1.1

Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer <AccessToken>

Where:

  • <MY_ORD_ID> is your Coveo organization ID

  • <CONFIG_ID> is the configuration ID that you retrieved when you created the answer configuration in the Coveo Knowledge Hub.

  • <ACCESS_TOKEN> is your access token.

Request payload

{
  "q": "Which gloves are better for autumn?",
  "searchHub": "sports", 1
  "pipeline": "Sport goods pipeline",
  "pipelineRuleParameters": {
    "mlGenerativeQuestionAnswering": {
      "responseFormat": {
        "contentFormat": ["text/markdown", "text/plain"] 2
      },
      "citationsFieldToInclude": [ 3
        "firstFieldForCitations",
        "secondFieldForCitations"
      ]
    }
  },
  // ...
}
1 Specify this parameter only if you’re using a temporary access token that’s not associated with any specific search hub.
Note

If you’re using an API key or a search token which is set up to use with a specific search hub, you can omit this parameter. However, you must specify the search hub as a condition in your query pipeline configuration.
2 Makes sure the response is in the desired format. The possible values are "text/markdown" and "text/plain". It’s recommended to provide both values to ensure the answer displays in plain text if markdown formatting fails.
3 Specifies the fields to include in the citations. The fields must be present in the documents returned by the query.

For the full list of possible parameters, see the reference documentation. For example, in addition to the above, you might pass the following:

{
  // ...
  "context": {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}, 1
  "locale": "en-US", 2
}
1 Lets you define context you can leverage in query pipeline conditions.
2 Specifies the locale to use for the answer generation, when multiple locales are supported.

Response payload with the generated answer

The Answer API uses server-sent events to fulfill your requests. Each event stream starts with a headerMessageType event, then sends one or more messageType events with the answer text, then sends a citationsType event with the citations, and finally ends with an endOfStreamType event.

{
  "payloadType": "genqa.headerMessageType",
  "payload": "{\"answerStyle\":\"default\",\"contentFormat\":\"text/markdown\"}",
  "finishReason": null,
  "errorMessage": null,
  "statusCode": null
}
{
  "payloadType": "genqa.messageType",
  "payload": "{\"textDelta\":\"### Autumn gloves\\n\\nThe following types of gloves are better suited for...,\",\"padding\":\"123456789\"}",
  "finishReason": null,
  "errorMessage": null,
  "statusCode": null
}
{
  "payloadType": "genqa.citationsType",
  "payload": "{\"citations\":[{\"id\":\"42.34281$https://example.com/articles/gloves-8:3\",\"title\":\"Sport gloves classification\",\"uri\":\"https://example.com/articles/gloves\",\"clickUri\":\"https://example.com/articles/gloves\",\"permanentid\":\"37a2594e9158310706d4b85cde9299b519653427f9b095c53332b9342577\",\"text\":\"lorem ipsum gloves\",\"source\":\"example.com\"}]}",
  "finishReason": null,
  "errorMessage": null,
  "statusCode": null
}
{
  "payloadType": "genqa.endOfStreamType",
  "payload": "{\"answerGenerated\":true}",
  "finishReason": "COMPLETED",
  "errorMessage": null,
  "statusCode": null
}

See the Answer API in action

Your search interface should have a key action that triggers the generation of an answer, it might be making a search, asking a chatbot a question, and so on. You can check if the Answer API is working properly by triggering that action and seeing the generate request on the network tab of your browser’s developer tools.

A "generate" request to the Answer API on the Network tab of a browser | Coveo Platform

API Reference

For more details, see the Answer API reference.