Base URL

https://<hue-server-domain>/api/v1/ai/assistant

API Endpoint

/api/v1/ai/assistant

Method: POST

Request Headers

The following table lists the headers required for making requests


Header	Value	Description
Authorization	Bearer <your_cdp_access_token>	CDP access token for authentication
Content-Type	application/json	Request payload format

Request Body Parameters

The following table describes the fields in the request body:


Parameter	Type	Required	Description	Example
task	string	Yes	SQL AI functionality to perform. Generate is the only supported feature.	"generate"
dialect	string	Yes	SQL dialect for generation. Supported: hive, impala, trino.	"impala"
object_selectors	array	No	Optional array of strings identifying database and tables to constrain task scope. Note: If you do not define specific objects, the system automatically selects the most relevant databases and tables.	["sales_db.orders", "hr_db.employees"]
input	string	Yes	Natural language or Natural Query Language (NQL) describing the input.	"Retrieve count of active users grouped by country"
cache_mode	string	No	Cache policy for schema loading. Values: incremental (reuse loaded data), refresh (reload always).	"incremental"
db_top_k	integer	No	Number of top databases to consider for SQL generation. Default: 3.	3
table_top_k	integer	No	Number of top tables per db to consider. Default: 10.	10

Example Request


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
}

Response Body

The following table describes the fields in the response body:


Field	Type	Description	Example
sql	string	The generated or edited SQL query	"SELECT country, COUNT(*) FROM sales_db.orders WHERE status = 'active' GROUP BY country;"
assumptions	array	List of assumptions the AI made about input, schema, or intent	["Assuming 'active' status means status='active'."]
tables_used	array	List of database tables that the SQL references	["sales_db.orders"]

Example Response


{
  "response": "Generated SQL to get counts by country of active users.",
  "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"
  ]
}

Error Handling

The following table lists common HTTP status codes and descriptions to help with error handling:


HTTP Status Code	Reason	Description
400 Bad Request	Invalid or missing parameter	Returned when a required field is missing or invalid values are provided
401 Unauthorized	Missing or invalid token	Authentication failure; token missing, expired or invalid
403 Forbidden	Permission denied	User lacks permission to access endpoint or resource
500 Internal Server Error	Server error	Unexpected error occurred during processing

SQL AI REST API Documentation