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.

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.

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.

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​

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:

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.

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​

Header Name	Required	Value
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.

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

HTTPcURLJavaScriptPython

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.

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

HTTPcURLJavaScriptPython

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

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:

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.

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

HTTPcURLJavaScriptPython

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

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:

{
  "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.