Data Intelligence APIs

Data Intelligence applications enable you to extract insights from data sources using natural language inputs through the Gathr interface. Using the Data Intelligence APIs, you can perform tasks such as querying data and receiving prompt responses, utilizing the Completion, Suggest Graph, and Get Data APIs, which are explained below.

• Completion: Get a response to a question in various formats, including HTML, Markdown (MD), or Raw format.

• Suggest Graph: Get suggestions for graph details based on your query and the data file path obtained from the Completion API’s response.

• Get Data: Retrieve data from the specified file path, which can be obtained from the Completion API’s response.

• Get Applications: Retrieve a list of Data Intelligence applications available to the user.

Prerequisite #

Before executing any API calls, ensure you have the following:

• A Data Intelligence application created within your Gathr account.

• A valid Data Intelligence API Key for authentication.

API Access Rate Limit #

Optimize API usage with the rate limits given below:

Once the request limit is reached within a time frame (minute, hour, or day), further requests will be allowed once the next time window starts.

Note: These rate limits apply across organization.

For example, if you have 10 users within the same registered organization, the limit will be shared across those users.

Data Intelligence API Keys #

To access Gathr and perform tasks using APIs, you need Data Intelligence API Keys.

Provide the API key as a header for authentication in your API service platform.

Generate a Data Intelligence API Key #

To generate a Data Intelligence API key, follow these steps:

1. Log in to your Gathr account and navigate to the Settings > Advanced > Access Keys option.

   

2. In the Access Keys tab, under the Data Intelligence API Keys section, click on GENERATE KEY.

   

3. Provide a unique name for the API key.

   

   A new Data Intelligence API Key will be generated.

4. Copy the API key and store it securely.

   

5. Click on DONE to permanently mask the generated API key. This action prevents any misuse of the API key.

   

   Once the key is masked, it cannot be reaccessed. However, you can always generate a new key.

Delete a Data Intelligence API Key #

Follow these steps to delete a Data Intelligence API Key:

1. Log in to your Gathr account and navigate to the User Profile page.

2. In the Access Keys tab, under the Data Intelligence API Keys section, identify the API key you want to permanently delete and click on Delete Key.

   

   A confirmation will be required to delete the API Key.

   Caution: Deleting API key will disable Gathr Rest API authentication.

Supported API Types and Example Code #

Interact with the Data Intelligence application using REST API services.

For the application you want to use APIs, select the API CODE option for the same as shown below:

From the API Type drop-down choose the API to get its sample request format and see the sample response.

• Completion

• Suggest Graph

• Get Data

• Get Applications

Each API has a sample cURL/Python code for making the request and a sample response, showing the API request format and expected response for easy integration into the API platform.

• cURL: Use cURL for quick, terminal-based testing and simple API requests.

• Python Code: Use Python code when integrating API calls into a larger Python application.

Completion API #

Get a response to a question in various formats, including HTML, Markdown (MD), or Raw format.

Request URL #

https://app.gathr.ai/api/v1/chat/completions

Headers #

• Authorization: Bearer <api_key>

• Content-Type: application/json

• responseType: <raw|html|md>

Request Body #

{
  "model": "Online_Retail_Store",
  "messages": [{"content": "<your_query>", "role": "user"}]
}

Request Body Parameters Details #

• model: The model used to process the request (for example, "Online_Retail_Store").

• messages: The user’s message to ask a question. The role should be "user".

• responseType: The desired response format (raw, html, md).

Response #

{
    "created": 1741160243521,
    "model": "Online_Retail_Store",
    "service_tier": "default",
    "id": "d953dc6b-6100-4074-b9f0-e286f5569adb",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "<response_content>"
            },
            "finish_reason": "stop"
        }
    ],
    "system_fingerprint": "dd8fadd6-b59d-469c-8056-6097fcc7206c",
    "object": "chat.completion"
}

cURL Example #

Use this sample in the command line or terminal:

curl --location 'https://app.gathr.ai/api/v1/chat/completions' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --header 'responseType: raw' \
  --data '{
    "model": "Online_Retail_Store",
    "messages": [{"content": "Get tables for REGULAR_PAY and PAY_YEAR.", "role": "user"}]
  }'

Python Example #

Use this sample in your Python code to interact with the API:

from openai import OpenAI

client = OpenAI(
    base_url="https://app.gathr.ai/api/v1",  # Your custom API URL
    api_key="<api_key>"  # Your API key
)

extra_headers = {'responseType': 'html'}  # or 'raw', 'md'

response = client.chat.completions.create(
    model="Online_Retail_Store",
    messages=[{"role": "user", "content": "Get tables for REGULAR_PAY and PAY_YEAR."}],
    extra_headers=extra_headers
)

# Print the assistant's reply from the choices
print(response.choices[0].message)

Suggest Graph API #

Get suggestions for graph details based on your query and the data file path provided.

Request URL #

https://app.gathr.ai/v1/chat/suggestGraph

Headers #

• Authorization: Bearer <api_key>

• Content-Type: application/json

Request Body #

{
  "model": "TestESConnection",
  "graphType": "Custom",
  "dataFilePath": "/data/file/path",
  "query": "generate a graph for REGULAR_PAY and PAY_YEAR"
}

Request Body Parameters Details #

• model: The model used to process the request (for example, "TestESConnection").

• graphType: The type of graph to generate (for example, "Custom", "Vertical Bar Chart", "Line Chart", "Donut Chart", "Pie Chart", "Scatter Chart", "Area Chart").

• dataFilePath: The file path for the data to generate the graph.

• query: User query to generate custom graph (for example, "generate a graph for REGULAR_PAY and PAY_YEAR").

Response #

{
  "graphSuggestion": {
    "graphType": "Custom",
    "x_axis": "PAY_YEAR",
    "y_axis": "REGULAR_PAY",
    "color_by": "DEPARTMENT_TITLE",
    "sorting_field": "REGULAR_PAY",
    "sorting_direction": "desc",
    "title": "Regular Pay by Year and Department",
    "x_axis_display_name": "Pay Year",
    "y_axis_display_name": "Regular Pay"
  }
}

cURL Example #

Use this sample in the command line or terminal:

curl --location 'https://app.gathr.ai/v1/chat/suggestGraph' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "TestESConnection",
    "graphType": "Custom",
    "dataFilePath": "/data/file/path",
    "query": "generate a graph for REGULAR_PAY and PAY_YEAR"
  }'

Python Example #

Use this sample in your Python code to interact with the API:

import requests
import json

url = "https://app.gathr.ai/v1/chat/suggestGraph"
api_key = "<api_key>"  # Your API key

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

data = {
    "model": "TestESConnection",
    "graphType": "Custom",
    "dataFilePath": "/data/file/path",
    "query": "generate a graph for REGULAR_PAY and PAY_YEAR"
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error {response.status_code}: {response.text}")

Get Data API #

Retrieve data from the specified file path.

Request URL #

https://app.gathr.ai/api/v1/chat/getData

Headers #

• Authorization: Bearer <api_key>

• Content-Type: application/json

Request Body #

{
  "model": "TestESConnection",
  "dataFilePath": "/data/file/path"
}

Request Body Parameters Details #

• model: The model used to process the request (for example, "TestESConnection").

• dataFilePath: The file path for the data you want to retrieve.

Response #

{
  "data": "RECORD_NBR,PAY_YEAR,DEPARTMENT_TITLE,JOB_TITLE,REGULAR_PAY\\n354000000000.0,2017,WATER AND POWER,GNL MGR & CHF ENGR WP,348670.0"
}

cURL Example #

Use this sample in the command line or terminal:

curl --location 'https://app.gathr.ai/api/v1/chat/getData' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "TestESConnection",
    "dataFilePath": "/data/file/path"
  }'

Python Example #

Use this sample in your Python code to interact with the API:

import requests
import json

url = "https://app.gathr.ai/v1/chat/getData"
api_key = "<api_key>"  # Your API key

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

data = {
    "model": "TestESConnection",
    "dataFilePath": "/data/file/path"
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error {response.status_code}: {response.text}")

Get Applications API #

Retrieve a list of Data Intelligence applications available to the user.

Request URL #

https://app.gathr.ai/api/v1/chat/applications

Headers #

• Authorization: Bearer <api_key>

• Content-Type: application/json

Request Body #

{
  "pageNumber": 1,
  "pageSize": 2,
  "projectName": "Default"
}

Request Body Parameters Details #

• pageNumber: (Optional) The page number for pagination.

• pageSize: (Optional) The number of applications to return per page.

• projectName: (Optional) The name of the project to filter applications by.

Note: If these parameters are not provided, the API will return all applications associated with the API key.

Response #

{
    "totalRecords": 10,
    "data": [
        {
            "role": "admin",
            "description": "",
            "dateModified": 1746443057582,
            "tags": [],
            "dateCreated": 1746443057572,
            "sourceType": "postgres",
            "createdBy": "ama@mailinator.com",
            "name": "GathrManagedApp5",
            "connectionId": "9882dcc9-ecda-4610-a969-cb3c178fd22d",
            "modifiedBy": "ama@mailinator.com",
            "connectionName": "PG_AMA",
            "projectName": "Default",
            "syncStatus": "Synced"
        },
        {
            "role": "admin",
            "description": "",
            "dateModified": 1746183650941,
            "tags": [],
            "dateCreated": 1746183650923,
            "sourceType": "postgres",
            "createdBy": "ama@mailinator.com",
            "name": "Managed",
            "connectionId": "9882dcc9-ecda-4610-a969-cb3c178fd22d",
            "modifiedBy": "ama@mailinator.com",
            "connectionName": "PG_AMA",
            "projectName": "Default",
            "syncStatus": "Synced"
        }
    ],
    "message": "List fetched successfully",
    "status": "SUCCESS"
}

cURL Example #

Use this sample in the command line or terminal:

curl --location 'https://app.gathr.ai/api/v1/chat/applications' \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "pageNumber": 1,
    "pageSize": 2,
    "projectName": "Default"
  }'

Python Example #

Use this sample in your Python code to interact with the API:

import requests
import json

url = "https://app.gathr.ai/api/v1/chat/applications"
api_key = "<api_key>"  # Your API key

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

data = {
    "pageNumber": 1,
    "pageSize": 2,
    "projectName": "Default"
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error {response.status_code}: {response.text}")

Data Intelligence API Response Codes #

Common HTTP status codes and their corresponding responses for the Data Intelligence API.