Chat Explore
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.
Custom Instructions
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.
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.
Data Formatting
Images
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.
Tables
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:
[
{
"firstName": "John",
"lastName": "Doe",
"age": 23
},
{
"firstName": "Joanna",
"lastName": "Adams",
"age": 45
}
]
Corresponding to this table:
John
Doe
23
Joanna
Adams
45
Statelessness
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.
HTTP Headers
X-API-Key
Yes
Your team's API key. See Authentication.
1. Create Request
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.
Query Chat Explore through API. Takes in a list of messages and gives you the message Chat Explore sent back.
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
""
""
The dataset ID which you want to run a Chat Explore query against. Either this or project_id must be specified.
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.
POST /api/v1/chat-explore/new HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 231
{
"chatContext": "",
"chatInstructions": "",
"dataset_id": "text",
"messages": [
{
"content": "text",
"images": [
"text"
],
"role": "user",
"table": [
{}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"project_id": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
{
"task_id": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
You'll receive an object like this containing a task id:
{
"task_id": "<task_id>"
}
We'll use this in the next request.
2. Query for Task Status
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.
Retrieves the status of the provided Chat Explore task id.
GET /api/v1/chat-explore/status/{task_id} HTTP/1.1
Host:
Accept: */*
{
"metadata": {
"type": "PENDING",
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"status": "PENDING",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
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:
{
"status": "SUCCEEDED",
"metadata": {
"type": "SUCCEEDED",
"location": "/api/v1/chat-explore/chats/<chat_id>"
}
}
Or, as a cURL command:
curl https://api.akkio.com/api/v1/chat-explore/status/task_id_from_previous_result \
-H "X-API-Key: your_api_key"
Armed with this information, we'll move to the last request.
3. Query for Result
Armed with the location we got from the status call, we'll make a request for the end chat.
Retrieves a chat by id.
GET /api/v1/chat-explore/chats/{id} HTTP/1.1
Host:
Accept: */*
{
"_org": "text",
"_owner": "text",
"messages": [
{
"content": "text",
"images": [
"text"
],
"role": "user",
"table": [
{}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"ANY_ADDITIONAL_PROPERTY": "anything"
}
A successful response looks something like this:
{
"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
}
]
}
Or, as a cURL command:
curl https://api.akkio.com/api/v1/chat-explore/chats/<chat_id> \
-H "X-API-Key: your_api_key"
You can take this result and use it however you wish.
Last updated
Was this helpful?