API Reference / 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 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

Verb Path Method

POST

/1/answers/{indexName}/prediction

Find answers

Find answers

A

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
Required

The two letter ISO code for language of the query, for example: ["en"] for English. Currently supports one language at the time.

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

Attributes to use for predictions. If using the default (["*"]), all attributes are used to find answers.

searchParameters
type: object
Optional

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

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.

returnExtractAttribute
type: boolean
default: true
Optional

Whether the attribute name in which the answer was found should be returned. This option is expensive in processing time.

semanticHighlight
type: int
default: 0
Optional

Controls the number of semantic highlights in the Answers response. When set to n, the first n extracts contain semantic highlights. The semantic highlight show the core of the answer within the paragraph, and allow your users to find it at one glance. The semantic highlight is associated with a score, accessible through the semanticHighlightScore in the Answers response.

Please note that processing time scale linearly by 100ms for each semantic highlight.

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.

Example:

A

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"
}

Did you find this page helpful?