Our Chat Explore endpoints allow you to interface with Chat Explore, our flagship "chat with your data" assistant. Our API allows a programmatic interface by which you can supply a project or dataset and a question you'd like to ask about it, and we'll respond with an answer.
As with most other long-running requests, we adopt an asynchronous endpoints model. You can read more about it on the Asynchronous Endpoints page or continue reading here.
Chat Explore has the powerful capability for you to provide Custom Instructions that allow you to attach additional context for each call specific to your use case.
NOTE:
In order for Chat Explore to factor in custom instructions attached to the project into calls, you must make these calls with the project_id parameter rather than the dataset_id parameter.
Three parameters may be specified:
chatContext: What you'd like Chat Explore to know about your application to provide better responses. Examples:
This dataset is customer engagement data
The units of the sales column are in millions
chatInstructions: Specifics on how you'd like Chat Explore to respond. Examples:
Respond only in Spanish
Provide short and concise answers only
chatSuggestions: The Web UI (app.akkio.com) intelligently generates a list of example questions you may ask Chat Explore as a good starting point. You can customize these instructions by providing a newline-separated list of what you'd like these suggestions to be. Example:
What is the average net media cost by campaign ID?
Please show me a chart of the distribution of customer ages.
Please show me a bar chart of company size.
For information on programmatically updating these parameters for a given project, see the Projects endpoints page.
Similar to the UI, we support returning charts and graphs to support our responses. Each message has an images field that represents a list of Base64-encoded images attached to that message.
NOTE:
Images are currently Base64 encoded in the .png format, but may be changed. You can assume a Base64-encoded image, but do not assume it will always be a .png image.
Tables are returned as a List of <string, value> maps, where each element of the list corresponds to a row, then each element has a key representing the column name and a value representing the value of that column.
For example, here's how a two-row table of user objects might look like:
Corresponding to this table:
firstName
lastName
age
John
Doe
23
Joanna
Adams
45
NOTE:
Values can be anything JSON-serializable - strings, numbers, floats, and so on - not necessarily a string.
Requests to this API are stateless. To emulate a full conversation, simply take our response from your previous query and add it to the messages array of your next query. You do not need to explicitly pass any kind of reference to your last query.
Request Sequence
Here's a rough outline of how you'd make a request to the Chat Explore API.
First, we'll submit a chat creation request. This will submit the task into our asynchronous processing queue and we'll begin working on it.
Submit Chat Explore Query
post
Query Chat Explore through API. Takes in a list of messages and gives you the message Chat Explore sent back.
Body
chatContextstringOptional
Anything you'd like Chat Explore to know about this application to provide better responses. For example: (1) This dataset is customer engagement data, (2) The units of the sales column are in millions, (3) The data is messy and contains typos
Default: ""
chatInstructionsstringOptionalDefault: ""
dataset_idany ofOptional
The dataset ID which you want to run a Chat Explore query against. Either this or project_id must be specified.
stringOptional
or
nullOptional
project_idany ofOptional
The project ID which you want to run a Chat Explore query against. Either this or dataset_id must be specified; if this is specified, custom instructions attached to the project will be provided as context to the query.
stringOptional
or
nullOptional
Other propertiesanyOptional
Responses
201
Successful Response
application/json
422
Validation Error
application/json
post
/api/v1/chat-explore/new
You'll receive an object like this containing a task id:
Next, we'll query the status endpoint at a cadence to see whether the chat is done being created yet. Note that you must use the same Task ID that you received from the task creation endpoint above.
Get Chat Explore Status
get
Retrieves the status of the provided Chat Explore task id.
Path parameters
task_idstringRequired
Responses
200
Successful Response
application/json
422
Validation Error
application/json
get
/api/v1/chat-explore/status/{task_id}
This will provide you with a status field set to either SUBMITTED, IN_PROGRESS, FAILED, or SUCCEEDED. You can read more about each state on the Asynchronous Endpoints page.
You should retry ("poll") this endpoint at a regular cadence until you get a response that looks something like this:
NOTE:
The location field is always relative to the API root (https://api.akkio.com/api/v1), not the overall website root (https://api.akkio.com). You'll need to remember to construct the end URL from the site name, API root, and the provided location.
Or, as a cURL command:
Armed with this information, we'll move to the last request.
Armed with the location we got from the status call, we'll make a request for the end chat.
Get Chat
get
Retrieves a chat by id.
Path parameters
idstringRequired
Query parameters
image_formatany ofOptional
string · enumOptionalPossible values:
or
nullOptional
Responses
200
Successful Response
application/json
422
Validation Error
application/json
get
/api/v1/chat-explore/chats/{id}
NOTE:
If you're interested in the images returned and you would prefer it to be formatted as a string-serialized Plotly JSON object instead of the default base64-encoded .png, pass in a image_format=plotly_json query parameter, and they'll be returned as such.
A successful response looks something like this:
Or, as a cURL command:
You can take this result and use it however you wish.
{
"owner": "<owner id>",
"org": "<org id>",
"messages": [
{
"role": "assistant",
"content": "Let's create a scatter plot to visualize the relationship between the living area (in square feet) and the price of the properties.",
"images": null,
"table": null
},
{
"role": "assistant",
"content": "A chart or table will be rendered here. Chat Explore doesn't have direct access to your chart, so it can't read what's on it.",
"images": [
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAArwAAAH0CAYAAADfWf7fAAAgAElEQVR4XuydBZhUVRvH/7uzXXR3CSKolI0BIgooAtLd3d3d3SXd0goifGIrCijSXdLNdkzs97xnmGU2WO7szs5s/O/zfM+HO+eec+7vnJn7u+9977ku0dHR0eBGAiRAAiRAAiRAAiRAAumUgAuFN52OLA [...] AAASUVORK5CYII="
],
"table": null
}
]
}
