API Response

The mosaix NLU engine returns a JSON object to each https POST request.

Sample response

{
  "version": "0.1.0",
  "mode": "query",
  "utterance": "play taylor swift",
  "session": {},
  "id": "605d6285-4cae-4a1e-890b-eef50a1c6e2a",
  "interpretations": [...]
}

Descriptions

version

 The engine version.

mode

 The query mode.

utterance

 User's original query in text string.

interpretations

 The interpretations, a list that holds all the results parsed by the NLU engine and their corresponding fulfillment.

 Each interpretation represent how NLU engine understand the meaning of user's query, thus generate the corresponding
 result based on that particular interpretation.

 All the interpretations in the list are in descending order, which means the first interpretation of the list has highest confidence score in terms
 of parsing user's query.

 There could be one or multiple interpretations returned. For multiple interpretations, each of them could belong to the same domain,
 like entertainment, or even cross domains. The client application needs to make decision which interpretations to go with and how to use them.

-A sample interpretation

Response Status Code

The API uses the following response status codes, as defined in the RFC 2616 and RFC 6585:

| Code |       Description       |
| ---- | :---------------------: |
| 200  |          *OK*           |
| 201  |        *Created*        |
| 202  |       *Accepted*        |
| 204  |      *No Content*       |
| 304  |     *Not Modified*      |
| 400  |      *Bas Request*      |
| 401  |     *Unauthorized*      |
| 403  |       *Forbidden*       |
| 404  |       *Not Found*       |
| 429  |   *Too Many Request*    |
| 500  | *Internal Server Error* |
| 502  |      *Bad Gateway*      |
| 503  |  *Service Unavailable*  |

Error Details

400:

You are authorized, but your request failed for possible one of the following reasons

{
  "status": 400,
  "reason": "post body does not match token scopes"
}

{
  "status": 400,
  "reason": "need a valid array of scopes"
}

{
  "status": 400,
  "reason": "need a valid spotify token"
}

{
  "status": 400,
  "reason": "need a valid npr token"
}

{
  "status": 400,
  "reason": "need an email to register"
}

{
  "status": 400,
  "reason": "invalid email"
}

{
  "status": 400,
  "reason": "need a valid verification token"
}

401:

We are not able to authorize you for possible one of the following reasons

{
  "status": 401,
  "reason": "api token has expired"
}

{
  "status": 401,
  "reason": "need a valid api token"
}

{
  "status": 401,
  "reason": "need a valid clientId and a valid clientSecret"
}

404:

Endpoint not found

503:

NLU engine is down

...with more to come