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

Joanna

Adams

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_idstring · nullableOptional

The dataset ID which you want to run a Chat Explore query against. Either this or project_id must be specified.

project_idstring · nullableOptional

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.

Other propertiesanyOptional

Responses

201

Successful Response

application/json

task_idstringRequired

The ID of the task that was started. This is generally queryable at a nearby /status endpoint to get the current status of the task.

Other propertiesanyOptional

422

Validation Error

application/json

post/api/v1/chat-explore/new

POST /api/v1/chat-explore/new HTTP/1.1
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

metadataone ofRequired

Metadata, contextually dependent on the status of the task being queried.

statusstring · enumRequired

The current status of the task being queried.

Possible values:

Other propertiesanyOptional

422

Validation Error

application/json

get/api/v1/chat-explore/status/{task_id}

GET /api/v1/chat-explore/status/{task_id} HTTP/1.1
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_formatstring · enum · nullableOptionalPossible values:

Responses

200

Successful Response

application/json

_orgstringRequired

Foreign key to the organization this object belongs to.

_ownerstringRequired

Foreign key to the user this object belongs to.

Other propertiesanyOptional

422

Validation Error

application/json

get/api/v1/chat-explore/chats/{id}

GET /api/v1/chat-explore/chats/{id} HTTP/1.1
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.

PreviousEndpoints NextProjects

Last updated 1 year ago

Was this helpful?

Custom Instructions​

Data Formatting​

Images​

Tables​

Statelessness​

Request Sequence

HTTP Headers​

1. Create Request​

Submit Chat Explore Query

2. Query for Task Status​

Get Chat Explore Status

3. Query for Result​

Get Chat

Custom Instructions

Data Formatting

Images

Tables

Statelessness

HTTP Headers

1. Create Request

2. Query for Task Status

3. Query for Result