# 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](https://docs.akkio.com/akkio-docs/concepts/asynchronous-endpoints) page or continue reading here. ### Custom Instructions[​](https://api-docs.akkio.com/endpoints/chat-explore#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. {% hint style="info" %} **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. {% endhint %} 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](https://docs.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/broken-reference) endpoints page.
### Data Formatting[​](https://api-docs.akkio.com/endpoints/chat-explore#data-formatting) #### Images[​](https://api-docs.akkio.com/endpoints/chat-explore#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. {% hint style="info" %} **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. {% endhint %} #### Tables[​](https://api-docs.akkio.com/endpoints/chat-explore#tables) Tables are returned as a List of \ 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:
firstNamelastNameage
JohnDoe23
JoannaAdams45
{% hint style="info" %} **NOTE:** Values can be anything JSON-serializable - strings, numbers, floats, and so on - not necessarily a string. {% endhint %} #### Statelessness[​](https://api-docs.akkio.com/endpoints/chat-explore#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[​](https://api-docs.akkio.com/endpoints/chat-explore#http-headers)
Header NameRequiredValue
X-API-KeyYesYour team's API key. See Authentication.
### 1. Create Request[​](https://api-docs.akkio.com/endpoints/chat-explore#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 > Query Chat Explore through API. Takes in a list of messages and gives you the message Chat Explore sent back. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/chat-explore/new":{"post":{"description":"Query Chat Explore through API. Takes in a list of messages and gives you the message Chat Explore sent back.","operationId":"_submit_chat_explore_query_api_v1_chat_explore_new_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatExploreRequestPayload"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APITaskStartedResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Submit Chat Explore Query","tags":["Chat Explore"]}}},"components":{"schemas":{"ChatExploreRequestPayload":{"additionalProperties":true,"properties":{"chatContext":{"default":"","description":"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","title":"Chatcontext","type":"string"},"chatInstructions":{"default":"","title":"Chatinstructions","type":"string"},"dataset_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The dataset ID which you want to run a Chat Explore query against. Either this or project_id must be specified.","title":"Dataset Id"},"messages":{"description":"A list of messages to query Chat Explore with.","items":{"$ref":"#/components/schemas/APIChatMessage"},"title":"Messages","type":"array"},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"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.","title":"Project Id"}},"required":["messages"],"title":"ChatExploreRequestPayload","type":"object"},"APIChatMessage":{"additionalProperties":true,"properties":{"content":{"description":"The text content of this message.","title":"Content","type":"string"},"images":{"default":[],"description":"List of images for this message (potentially of length zero). May be exposed either as a base64 string or as stringified Plotly JSON, typically if the user requested it as such.","items":{"anyOf":[{"type":"string"},{"type":"object"}]},"title":"Images","type":"array"},"role":{"$ref":"#/components/schemas/RolesEnum","description":"The role of this message. User indicates the user sent the message, assistant indicates the assistant sent the message."},"table":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"description":"If there exists a table for this message, this will be set to a list of objects/records, where each record has a key of the column name and a value for that row's corresponding value for the column.","title":"Table"}},"required":["role","content"],"title":"APIChatMessage","type":"object"},"RolesEnum":{"enum":["user","assistant"],"title":"RolesEnum","type":"string"},"APITaskStartedResponse":{"additionalProperties":true,"properties":{"task_id":{"description":"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.","title":"Task Id","type":"string"}},"required":["task_id"],"title":"APITaskStartedResponse","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` You'll receive an object like this containing a task id: ``` { "task_id": "" } ``` We'll use this in the next request. ### 2. Query for Task Status[​](https://api-docs.akkio.com/endpoints/chat-explore#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 > Retrieves the status of the provided Chat Explore task id. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/chat-explore/status/{task_id}":{"get":{"description":"Retrieves the status of the provided Chat Explore task id.","operationId":"_get_chat_explore_status_api_v1_chat_explore_status__task_id__get","parameters":[{"in":"path","name":"task_id","required":true,"schema":{"title":"Task Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIStatusResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Get Chat Explore Status","tags":["Chat Explore"]}}},"components":{"schemas":{"APIStatusResponse":{"additionalProperties":true,"properties":{"metadata":{"description":"Metadata, contextually dependent on the status of the task being queried.","discriminator":{"mapping":{"FAILED":"#/components/schemas/APIStatusMetadataFailed","IN_PROGRESS":"#/components/schemas/APIStatusMetadataInProgress","PENDING":"#/components/schemas/APIStatusMetadataPending","SUCCEEDED":"#/components/schemas/APIStatusMetadataSucceeded"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/APIStatusMetadataPending"},{"$ref":"#/components/schemas/APIStatusMetadataInProgress"},{"$ref":"#/components/schemas/APIStatusMetadataSucceeded"},{"$ref":"#/components/schemas/APIStatusMetadataFailed"}],"title":"Metadata"},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"The current status of the task being queried."}},"required":["status","metadata"],"title":"APIStatusResponse","type":"object"},"APIStatusMetadataPending":{"additionalProperties":true,"properties":{"type":{"const":"PENDING","default":"PENDING","enum":["PENDING"],"title":"Type","type":"string"}},"title":"APIStatusMetadataPending","type":"object"},"APIStatusMetadataInProgress":{"additionalProperties":true,"properties":{"estimate_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"If provided, an estimate of how many seconds we expect this task to take. This value should be treated as a rough estimate on a best-effort basis, not a guarantee.","title":"Estimate Seconds"},"type":{"const":"IN_PROGRESS","default":"IN_PROGRESS","enum":["IN_PROGRESS"],"title":"Type","type":"string"}},"title":"APIStatusMetadataInProgress","type":"object"},"APIStatusMetadataSucceeded":{"additionalProperties":true,"properties":{"location":{"description":"The path at which you can submit a GET request to retrieve the result of the successful job. May require proper authentication or authorization to access.","title":"Location","type":"string"},"type":{"const":"SUCCEEDED","default":"SUCCEEDED","enum":["SUCCEEDED"],"title":"Type","type":"string"}},"required":["location"],"title":"APIStatusMetadataSucceeded","type":"object"},"APIStatusMetadataFailed":{"additionalProperties":true,"properties":{"error":{"default":"Unable to complete request. Please verify your inputs, try again later, or get in touch at support@akkio.com.","description":"If provided, a text representation of what went wrong with the task, including if any action on your part may rectify the issue.","title":"Error","type":"string"},"type":{"const":"FAILED","default":"FAILED","enum":["FAILED"],"title":"Type","type":"string"}},"title":"APIStatusMetadataFailed","type":"object"},"TaskStatusEnum":{"description":"Celery task status enum. Update apps/web-backend-api/src/types/TaskStatusEnum.ts if you update this enum.","enum":["PENDING","IN_PROGRESS","SUCCEEDED","FAILED","UNKNOWN_TIMEOUT"],"title":"TaskStatusEnum","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` 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](https://docs.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/broken-reference) 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/" } } ``` {% hint style="info" %} **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. {% endhint %} 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[​](https://api-docs.akkio.com/endpoints/chat-explore#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 > Retrieves a chat by id. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/chat-explore/chats/{id}":{"get":{"description":"Retrieves a chat by id.","operationId":"_get_chat_api_v1_chat_explore_chats__id__get","parameters":[{"in":"path","name":"id","required":true,"schema":{"title":"Id","type":"string"}},{"in":"query","name":"image_format","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ChatExploreImageFormat"},{"type":"null"}],"title":"Image Format"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/_ApiBaseChatRecord"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Get Chat","tags":["Chat Explore"]}}},"components":{"schemas":{"ChatExploreImageFormat":{"enum":["base64_png","plotly_json"],"title":"ChatExploreImageFormat","type":"string"},"_ApiBaseChatRecord":{"additionalProperties":true,"properties":{"_org":{"description":"Foreign key to the organization this object belongs to.","title":" Org","type":"string"},"_owner":{"description":"Foreign key to the user this object belongs to.","title":" Owner","type":"string"},"messages":{"description":"List of messages in the chat.","items":{"$ref":"#/components/schemas/APIChatMessage"},"title":"Messages","type":"array"}},"required":["_owner","_org","messages"],"title":"_ApiBaseChatRecord","type":"object"},"APIChatMessage":{"additionalProperties":true,"properties":{"content":{"description":"The text content of this message.","title":"Content","type":"string"},"images":{"default":[],"description":"List of images for this message (potentially of length zero). May be exposed either as a base64 string or as stringified Plotly JSON, typically if the user requested it as such.","items":{"anyOf":[{"type":"string"},{"type":"object"}]},"title":"Images","type":"array"},"role":{"$ref":"#/components/schemas/RolesEnum","description":"The role of this message. User indicates the user sent the message, assistant indicates the assistant sent the message."},"table":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"description":"If there exists a table for this message, this will be set to a list of objects/records, where each record has a key of the column name and a value for that row's corresponding value for the column.","title":"Table"}},"required":["role","content"],"title":"APIChatMessage","type":"object"},"RolesEnum":{"enum":["user","assistant"],"title":"RolesEnum","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` {% hint style="info" %} **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. {% endhint %} A successful response looks something like this: ``` { "owner": "", "org": "", "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/ \ -H "X-API-Key: your_api_key" ``` You can take this result and use it however you wish.