Answers REST API

Overview

The Answers API enables semantic search on an existing index. It lets you bring your users directly to the part of your content that answers their questions.

This feature is currently in limited release. You can sign up to request access.

The Answers API is currently in limited release. There’s no SLA for products in limited release, it’s best to implement the API with a fallback mechanism.

Authentication

The API requires the application ID and API key to be passed through the following headers:

• X-Algolia-Application-Id: the application ID.
• X-Algolia-API-Key: the authentication token.

Optionally, those parameters (case sensitive) are also accepted as URL parameters.

The X-Algolia-API-Key needs to have the nluReadAnswers ACL.

You also need to have Answers enabled on your application.

Errors

In case of errors, the Answers API returns a 4XX or 5XX HTTP Status Code with a payload in the following format:

1
2
3
{
  "message": "description of the error and its potential cause"
}

When the error is due to a malformed request, the response includes a detail array that describe the errors found in the request. For example, if a request is missing the required query parameter and using invalid queryLanguages, the error message would look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "message": "Invalid input received.",
  "detail": [
    {
      "msg": "field required",
      "location": [
        "body",
        "query"
      ]
    },
    {
      "msg": "value is not a valid enumeration member; permitted: 'en'",
      "ctx": {
        "enum_values": [
          "en",
          "fr"
        ]
      },
      "location": [
        "body",
        "queryLanguages",
        0
      ]
    }
  ],
  "received": {
    "queryLanguages": [
      "foo"
    ]
  }
}

Answers

Quick Reference

Path: /1/answers/{indexName}/prediction
HTTP Verb: POST

Description:

Returns answers that match the query.

Parameters:

Errors:

• 401: Unauthorized. The credentials (application ID, API Key) are either missing, incorrect, or do not have the Answers feature enabled.
• 422: Unprocessable Entity. At least one request field is invalid. Check the detail field of the response for a list of identified errors.
• 400: InvalidSearchParameters. An Algolia index setting or search parameter is invalid.

1
2
3
4
5
6
7
8
9
10
11
curl -X POST https://${APPLICATION_ID}-dsn.algolia.net/1/answers/${INDEX_NAME}/prediction \
-H 'Content-Type: application/json' \
-H 'X-Algolia-Api-Key: ${API_KEY_WITH_ANSWERS_ACL}' \
-H 'X-Algolia-Application-ID: ${APPLICATION_ID}' \
-d '{
  "query": "when do babies start learning?",
  "queryLanguages": ["en"],
  "attributesForPrediction": ["description"],
  "searchParameters": {"attributesToRetrieve": [], "attributesToHighlight": []},
  "nbHits": 1
}'

When the query is successful, the HTTP response is a 200 OK containing the relevant hits. Each hit has a new _answer field containing the answer metadata:

• extract: the part of the record best answering the query
• extractAttribute: when requested, which attribute the extract comes from
• score: the confidence in the answer. Higher scores are better, with a score of 0 meaning the result is irrelevant to the query.

1
2
3
4
5
{
  "extract": "Pop quiz: When does <em>learning</em> begin? Answer: Before we are born. Science writer Annie Murphy Paul talks through new research that shows how much we learn in the womb -- from the lilt of our native language to our soon-to-be-favorite foods.",
  "score": 212.122,
  "extractAttribute": "description"
}