API Reference / REST API / Answers REST API

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 closed beta. You can sign up to request access.

The Answers API is currently in closed beta. While we expect no significant downtime, we do not offer SLA for products in beta. You should 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

Verb Path Method

POST

/1/answers/{indexName}/prediction

Find answers

Find answers

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

Description:

Returns answers that match the query.

Parameters:

query
type: string
Required

The query for which to retrieve results. Cannot be empty or spaces only.

queryLanguages
type: array
default: ["en"]
Optional

The languages in the query. Currently only supports en.

params
type: object
Optional

Algolia search parameters to use to fetch the hits. Can be any search parameter, except:

attributesForPrediction
type: array
default: ["*"]
Optional

Attributes to use for predictions. If empty, we use all searchableAttributes to find answers.

All your attributesForPrediction must be part of your searchableAttributes.

nbHits
type: int
default: 10
Optional

Maximum number of answers to retrieve from the Answers Engine. Cannot be greater than 1000.

threshold
type: float
default: 0.0
Optional

Threshold for the answers’ confidence score: only answers with extracts that score above this threshold are returned.

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: InvalidSearchParams. An Algolia index setting or search parameter is invalid.

Example:

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"],
  "params": {"attributesToRetrieve": [], "attributesToHighlight": []},
  "nbHits": 1
}'

When the query is successful, the HTTP response is a 200 OK containing the relevant hits augmented with their _answer.
Each Answer contains the part of its record best answering the query in extract, the attribute it comes from in extractAttribute, and a confidence score (higher scores are better, with a score of 0 meaning the result is irrelevant to the query):

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
{
  "nbPages": 2,
  "nbHits": 1,
  "params": "query=when+do+babies+start+learning%3F&attributesToRetrieve=%5B%5D&attributesToHighlight=%5B%5D&naturalLanguages=%5B%22en%22%5D&hitsPerPage=150&analyticsTags=%5B%22algolia-answers%22%5D&queryType=prefixNone&attributesToSnippet=%5B%22description%3A80%22%5D&restrictSearchableAttributes=%5B%22description%22%5D&queryLanguages=%5B%22en%22%5D&ignorePlurals=en&removeStopWords=en&removeWordsIfNoResults=allOptional&ruleContexts=natural_language&analyticsTags=algolia-answers%2Cnatural_language",
  "hitsPerPage": 150,
  "query": "when do babies start learning?",
  "exhaustiveNbHits": true,
  "hits": [
    {
      "objectID": "299357000",
      "_snippetResult": {
        "description": {
          "value": "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.",
          "matchLevel": "partial"
        }
      },
      "_answer": {
        "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"
      }
    }
  ],
  "processingTimeMS": 17,
  "page": 0
}

Did you find this page helpful?