Here we present the endpoints available on running NLIs. These endpoints return JSON expressions that represent table and list answers as well as a special choice list which lets users pick the proper interpretation of their question in case of ambiguity. There is also a simple endpoint to generate fresh session identifiers to track concurrent dialogues. The table below presents these endpoints. The python code at the bottom of this file shows this API being called for an example of the Geo NLI running at proxy port 8002 on


Method Endpoint Purpose Return Type
GET /c-phrase/v1/session Gets a new session id. session
GET /c-phrase/v1/request?session={int}&text={text} Asks the NLI to answer the given question text within the specified session. table-answer, list-answer, choice-list or error
GET /c-phrase/v1/choice?session={int}&choice={int} Chooses the n-th interpretation of the previous choice list within the given session. table-answer, list-answer or error

Return Types

All returned results are JSON expressions. In the examples below, assume that the geo NLI is running on port 9000 of the host


Sessions are integer ids that keep track of specific ongoing dialogues. There can be multiple concurrent sessions.

Table Answer

Table answers either are returned as a direct result of a request, or as the result of choosing an interpretation within a choice list (see below)

List Answer

List answers are similar to table answers, but they are over a single column. Importantly aggregate function results are lists of length one. See the second example below:

Choice List

A choice list gives all the interpretations for an ambiguous question. Immediately after a choice list is returned, then one of the interpretations may be picked on the next call via the choice endpoint. This in turn will generate a table answer, a list answer or, possibly, an error.


Errors are returned when something fails.

Calling the REST API from Python

This performs the examples above plus a final 'bar chart example' called from python for a Geo NLI running at proxy port 8002 at Note the use of the /api/csrf route to obtain a csrf_token and then /api/login route to authenticate under that token. Subsequent calls then use the authenticated token.

Also note the extra final call in this code which gives the raw data from which a chart may be constructed. This only works if the default chart building within C-Phrase is turned off. Namely, if the parameter cphrase.charts_on = False.

We shall leave out interface running, so executing this code in a python console should work.

import requests
import json

host = ''

auth = {

s = requests.Session()
csrf_token = s.get(host + '/api/csrf').text

h = {'X-CSRFToken': csrf_token}

response = + '/api/login', headers=h, json=auth)
session = json.loads(s.get(host + "/c-phrase/v1/session", headers=h).text)['session']

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=three longest rivers", headers=h).text)

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=names cities Michigan", headers=h).text)

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=largest state", headers=h).text)
if 'choices' in answer:
    answer = json.loads(s.get(host + f"/c-phrase/v1/choice?session={session}&choice=2", headers=h).text)

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=saskwatch", headers=h).text)

answer = json.loads(s.get(host + f"/c-phrase/v1/request?session={session}&text=how many cities per state", headers=h).text)