Data Warehouse Intelligence APIs

Data Warehouse Intelligence applications enable you to extract insights from data sources using natural language inputs through the Gathr interface. Using the Data Warehouse 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.

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

  • Conversations List: Retrieve a list of conversations associated with the specified model.

  • Conversation Questions: Get a list of questions associated with a specific conversation.

Prerequisite

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

  • A Data Warehouse Intelligence application created within your Gathr account.

  • A valid Data Warehouse Intelligence API Key for authentication.

API Access Rate Limit

Optimize API usage with the rate limits given below:

Requests per MinuteRequests per HourRequests per Day
22050

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 Warehouse Intelligence API Keys

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

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

Generate a Data Warehouse Intelligence API Key

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

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

    Data Warehouse Intelligence API Keys - Settings

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

    Data Warehouse Intelligence API Keys - Settings

  3. Provide a unique name for the API key.

    Data Warehouse Intelligence API Keys - Provide a Name

    A new Data Warehouse Intelligence API Key will be generated.

  4. Copy the API key and store it securely.

    Data Warehouse Intelligence API Keys - Generated

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

    Data Warehouse Intelligence API Keys - Saved

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

Delete a Data Warehouse Intelligence API Key

Follow these steps to delete a Data Warehouse 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 Warehouse Intelligence API Keys section, identify the API key you want to permanently delete and click on Delete Key.

    Delete API 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 Warehouse 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:

Access API Code

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

API Sample Code

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>

  • conversationId: <conversation_id> (optional, used to continue conversations in the same conversation thread. If not provided, a new conversation will be started. It’s value can be retrieved from the response of the previous API call.)

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

Application List API

Retrieve a list of Data Warehouse 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}")

Conversations List API

Get a list of conversations associated with the specified model.

Request URL 

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

Headers

  • Authorization: Bearer <api_key>

  • Content-Type: application/json

Request Body 

{
  "model": "TestUsability",
  "conversationStartTime": 0,
  "conversationEndTime": 0
}

Request Body Parameters Details

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

  • conversationStartTime: The start time of the conversation, in epoch time. 0 returns from the initial conversation.

  • conversationEndTime: The end time of the conversation, in epoch time. 0 returns until the last conversation.

Response 

{
  "conversations": [
    {
      "conversationId": "9ba46012-f78f-498f-942a-5656bc6ac594",
      "conversationHeading": "Give me some data related to best practices where",
      "conversationTime": 1751975993489
    },
    {
      "conversationId": "ed33efe2-d79b-4068-987f-903a7d224b77",
      "conversationHeading": "Give me some data related to best practices where",
      "conversationTime": 1751972129992
    },
    {
      "conversationId": "fee316f6-17fe-4eae-abba-66f56e2ca743",
      "conversationHeading": "Give me some data related to best practices where",
      "conversationTime": 1751972071417
    },
    {
      "conversationId": "26a69bf3-2865-4105-8ad4-dbeab7c2cbb6",
      "conversationHeading": "Give me some data related to best practices where",
      "conversationTime": 1751971821289
    },
    {
      "conversationId": "d808a62e-6078-4b17-8d38-37fa5b364330",
      "conversationHeading": "Give me some data related to best practices where",
      "conversationTime": 1751970587194
    },
    {
      "conversationId": "8c540008-e9e5-45c5-bb02-cc789766af88",
      "conversationHeading": "Give me some data related to best practices for the give filter based WHERE 'Feature' = 'Account difference'",
      "conversationTime": 1751970463789
    },
    {
      "conversationId": "d0324a45-b876-42ff-a340-987a46246225",
      "conversationHeading": "Give me some data related to best practices for the give filter based WHERE 'Feature' = 'Account difference'",
      "conversationTime": 1751970243140
    },
    {
      "conversationId": "f94476e4-953b-49a2-bef2-3cda9cfbc5a5",
      "conversationHeading": "Give me some data related to best practices for the give filter based WHERE 'Feature' = 'Account difference'",
      "conversationTime": 1751371464169
    },
    {
      "conversationId": "c79e7cf6-7003-4c89-a1ec-56f22f70a448",
      "conversationHeading": "Give me some data related to best practices for the give filter based WHERE 'Feature' = 'Account difference'",
      "conversationTime": 1751370465434
    },
    {
      "conversationId": "1b426e93-9e21-4c03-badf-55db63c2bf7e",
      "conversationHeading": "Give me some data related to best practices for the give filter based WHERE 'Feature' = 'Account difference'",
      "conversationTime": 1751370417365
    },
    {
      "conversationId": "18b4681f-8fe4-4e3a-b677-1c77e08d7ac1",
      "conversationHeading": "Give me some data related to best practices for the give filter based WHERE 'Feature' = 'Account difference'",
      "conversationTime": 1751370277986
    },
    {
      "conversationId": "498ea6f8-fdfc-421e-82fd-e868623396f1",
      "conversationHeading": "Give me some data related to best practices for the give filter based WHERE 'Feature' = 'Account difference'",
      "conversationTime": 1751370211684
    },
    {
      "conversationId": "4bff81fd-8ce8-46e7-b4b0-70a1c0beab92",
      "conversationHeading": "get me lesson learned for LL00079 and get the best practices associated this lesson learned. and get both the data separatly",
      "conversationTime": 1751368308695
    },
    {
      "conversationId": "f150dc24-3ca3-47c2-b1ec-5b9270fda0ae",
      "conversationHeading": "get me lesson learned for SS20",
      "conversationTime": 1751364296478
    },
    {
      "conversationId": "24d01aba-5053-4721-9672-50f051a49547",
      "conversationHeading": "get me lesson learned for LL00079 and get the best practices associated this lesson learned. and get both the data separatly",
      "conversationTime": 1751363160265
    }
  ],
  "lastConversationTime": -1
}

cURL Example

Use this sample in the command line or terminal:

curl --location 'https://app.gathr.ai/api/v1/chat/conversations' \
            --header 'Authorization: Bearer <api_key>' \
            --header 'Content-Type: application/json' \
            --header 'responseType: html' \
            --data '{"model": "TestUsability", "conversationStartTime": 0, "conversationEndTime": 0}'

Python Example

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

import requests
import json
           
          # Define the custom API URL and API key
          url = "https://app.gathr.ai/api/v1/chat/conversations"
          api_key = "<api_key>"  # Your API key
           
          # Set up the headers
          headers = {
              "Authorization": f"Bearer {api_key}",
              "Content-Type": "application/json"
          }
           
          # Define the payload (data to send in the POST request)
          data = {"model": "TestUsability", "conversationStartTime": 0, "conversationEndTime": 0}
           
          # Send the POST request
          response = requests.post(url, headers=headers, data=json.dumps(data))
           
          # Check if the request was successful (status code 200)
          if response.status_code == 200:
              # Parse the response
              response_data = response.json()
              print(response_data)
          else:
              # Print error if the request failed
              print(f"Error {response.status_code}: {response.text}")

Conversation Questions API

Get a list of questions associated with a specific conversation.

Request URL 

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

Headers

  • Authorization: Bearer <api_key>

  • Content-Type: application/json

Request Body 

{
  "model": "TestUsability",
  "conversationId": "d808a62e-6078-4b17-8d38-37fa5b364330",
  "pageNumber": 1,
  "pageSize": 20
}

Request Body Parameters Details

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

  • conversationId: The ID of the conversation to retrieve questions for.

  • pageNumber: The page number for pagination.

  • pageSize: The number of items per page.

Response 

{
  "questions": [
    {
      "questionId": "86a41b54-5bd7-4ff0-8754-fa16e542b8a6",
      "conversationId": "d808a62e-6078-4b17-8d38-37fa5b364330",
      "conversationTime": 1751970587194,
      "conversationEndTime": 1751970592604,
      "username": "demo@gathr.ai",
      "incidentId": "faad4d30-f853-4e02-8fcd-250c290d9c0f",
      "responseJson": "{\n    \"code\": \"500\",\n    \"message\": \"Failed to perform action due to an unexpected error. Please contact the application administrator with Incident ID : faad4d30-f853-4e02-8fcd-250c290d9c0f for further assistance.\",\n    \"status\": \"FAILURE\"\n}",
      "requestJson": "{\"model\": \"TestUsability\", \"messages\": [{\"role\": \"user\", \"content\": \"Question 1\"}, {\"role\": \"assistant\", \"content\": \"This appears to be a request for a code or SQL modification, which is out of scope for this application.\"}, {\"role\": \"user\", \"content\": \"Give me some data related to best practices where\"}]}"
    }
  ],
  "total": 1
}

cURL Example

Use this sample in the command line or terminal:

curl --location 'https://app.gathr.ai/api/v1/chat/conversationQuestions' \
            --header 'Authorization: Bearer <api_key>' \
            --header 'Content-Type: application/json' \
            --header 'responseType: html' \
            --data '{"model": "TestUsability", "conversationId": "d808a62e-6078-4b17-8d38-37fa5b364330", "pageNumber": 1, "pageSize": 20}'

Python Example

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

import requests
import json
           
          # Define the custom API URL and API key
          url = "https://app.gathr.ai/api/v1/chat/applications"
          api_key = "<api_key>"  # Your API key
           
          # Set up the headers
          headers = {
              "Authorization": f"Bearer {api_key}",
              "Content-Type": "application/json"
          }
           
          # Define the payload (data to send in the POST request)
          data = {"model": "TestUsability", "conversationId": "d808a62e-6078-4b17-8d38-37fa5b364330", "pageNumber": 1, "pageSize": 20}
           
          # Send the POST request
          response = requests.post(url, headers=headers, data=json.dumps(data))
           
          # Check if the request was successful (status code 200)
          if response.status_code == 200:
              # Parse the response
              response_data = response.json()
              print(response_data)
          else:
              # Print error if the request failed
              print(f"Error {response.status_code}: {response.text}")

Data Warehouse Intelligence API Response Codes

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

Status CodeSample ResponseRemarks
200{ "object": "chat.completion", "created": 1741764333922, "model": "Test", "id": "18320224-17f3-4bbc-9794-ef99bc5b5057", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello! How can I assist you with data analysis today?", "refusal": null }, "logprobs": null, "finish_reason": "stop" }], "service_tier": "default", "system_fingerprint": "649b0a81-9b02-4e4e-9950-cc66363b6672" }Successful response from the Data Warehouse Intelligence service.
500{ "code": "500", "message": "The Data Warehouse Intelligence service is temporarily unavailable. Please try again later.", "status": "FAILURE" }Temporary unavailability or internal error in the Data Warehouse Intelligence service.
412{ "code": "412", "error": "Unable to access the Data Warehouse Intelligence application {appName} with the provided API key." }Incorrect API key or access issue with the specified application.
429{ "code": "429", "error": "Data Warehouse Intelligence API rate limit reached for the minute." }Rate limit exceeded.
401{ "code": "401", "error_description": "The access token is expired or invalid", "error": "UnAuthorized Access" }Expired or invalid access token.
422{ "code": "422", "error": "Please provide a valid value for model." }Missing or incorrect value for a required key.

If you have any feedback on Gathr documentation, please email us!

← View Users Access
Starburst Connection →