Authenticating API Request

Base URL

https://[***hue-server-domain***]/api/v1/ai/assistant

Replace the [***hue-server-domain***] with the actual server domain.

API Endpoint

Endpoint: /api/v1/ai/assistant

Method: POST

Request Headers

The following table describes the required request headers:

Request Body Parameters

The following table describes the request body parameters:

Generate

The following example displays a POST request payload for the Generate task:

POST /api/v1/ai/assistant HTTP/1.1
Host: hue.company.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "task": "generate",
  "dialect": "impala",
  "object_selectors": ["sales_db.orders", "hr_db.employees"],
  "input": "Get the count of active users grouped by country",
  "cache_mode": "incremental",
  "db_top_k": 2,
  "table_top_k": 5
}
      

The following example displays an example API response payload:

{
  "response": {
    "sql": "SELECT country, COUNT(*) as active_user_count FROM sales_db.orders WHERE status = 'active' GROUP BY country;",
    "assumptions": [
      "Assuming 'active' status means status='active'."
    ]
  },
  "tables_used": [
    "sales_db.orders"
  ]
}
      

Edit

The following example displays an POST request payload for the Edit task:

POST /api/v1/ai/assistant HTTP/1.1
Host: hue.company.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "task": "edit",
  "dialect": "impala",
  "object_selectors": ["sales_db.orders"],
  "input": "Only include orders placed in the last 30 days and sort by amount descending",
  "sql": "SELECT * FROM sales_db.orders"
}
      

The following example displays an example API response payload:

{
  "response": {
    "sql": "SELECT *\nFROM sales_db.orders\nWHERE order_date >= NOW() - INTERVAL 30 DAYS\nORDER BY amount DESC",
    "assumptions": [
      "Assumed order_date is a timestamp column and amount stores the order value."
    ]
  },
  "tables_used": [
    "sales_db.orders"
  ]
}
      

Explain

The following example displays an POST request payload for the Explain task:

POST /api/v1/ai/assistant HTTP/1.1
Host: hue.company.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "task": "explain",
  "dialect": "hive",
  "object_selectors": ["sales_db"],
  "sql": "SELECT c.name, SUM(o.amount) FROM sales_db.customers c JOIN sales_db.orders o ON c.customer_id = o.customer_id GROUP BY c.name"
}
      

The following example displays an example API response payload:

{
  "response": {
    "explanation": "The query joins customers to their orders on customer_id, groups the rows by customer name, and sums the order amount within each group to produce the total spend per customer.",
    "summary": "Returns the total order amount for each customer by name."
  },
  "tables_used": [
    "sales_db.customers",
    "sales_db.orders"
  ]
}
      

Optimize

The following example displays an POST request payload for the Optimize task:

POST /api/v1/ai/assistant HTTP/1.1
Host: hue.company.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "task": "optimize",
  "dialect": "impala",
  "object_selectors": ["sales_db"],
  "sql": "SELECT * FROM sales_db.orders o WHERE o.customer_id IN (SELECT customer_id FROM sales_db.customers WHERE region = 'US')"
}
      

The following example displays an example API response payload:

{
  "response": {
    "sql": "SELECT o.*\nFROM sales_db.orders o\nJOIN sales_db.customers c ON o.customer_id = c.customer_id\nWHERE c.region = 'US'",
    "explanation": "Rewrote the IN subquery as a JOIN so the planner can use a hash join, and selected only the needed columns instead of SELECT *.",
    "assumptions": [
      "Assumed customer_id is unique in customers so the JOIN does not duplicate order rows."
    ]
  },
  "tables_used": [
    "sales_db.orders",
    "sales_db.customers"
  ]
}
      

Fix

The following example displays an POST request payload for the Fix task:

POST /api/v1/ai/assistant HTTP/1.1
Host: hue.company.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "task": "fix",
  "dialect": "hive",
  "object_selectors": ["sales_db"],
  "sql": "SELECT customer_id, SUM(amount) FROM sales_db.orders"
}
      

The following example displays an example API response payload:

{
  "response": {
    "sql": "SELECT customer_id, SUM(amount)\nFROM sales_db.orders\nGROUP BY customer_id",
    "explanation": "The query aggregated amount with SUM() but selected the non-aggregated customer_id without a GROUP BY clause. Added GROUP BY customer_id.",
    "assumptions": [
      "Assumed the intent was one aggregated row per customer_id."
    ]
  },
  "tables_used": [
    "sales_db.orders"
  ]
}
      

Comment

The following example displays an POST request payload for the Comment task:

POST /api/v1/ai/assistant HTTP/1.1
Host: hue.company.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "task": "comment",
  "dialect": "trino",
  "object_selectors": ["sales_db"],
  "sql": "SELECT c.name, SUM(o.amount) FROM sales_db.customers c JOIN sales_db.orders o ON c.customer_id = o.customer_id GROUP BY c.name"
}
      

The following example displays an example API response payload:

{
  "response": {
    "sql": "SELECT c.name, SUM(o.amount) /* total spend per customer */\nFROM sales_db.customers c\nJOIN sales_db.orders o ON c.customer_id = o.customer_id /* link each order to its customer */\nGROUP BY c.name /* one row per customer */"
  },
  "tables_used": [
    "sales_db.customers",
    "sales_db.orders"
  ]
}