POST /api/v202606/edx/ai/generate

Generates a KQL query from a natural-language question.

GenerateV202606

The prompt is answered only from the EDX-queryable schema; a question that cannot be expressed against those tables returns with success = false and a reason in the error field rather than an HTTP error. The returned KQL is validated by the engine, so the valid field indicates whether it is safe to run as-is, and attempts reports how many generate/validate passes were needed.

Request Headers

Header	Value	Required	Description
ECI-ApiKey	string	Yes	Your API key. See Authentication.
Content-Type	application/json	Yes	All requests must specify JSON content type, including the request body.

Request Body

EdxAiGenerateRequestV202606

Property	Description	Type
prompt		string

Example Request Body application/json

{  "prompt": "string"
}

Responses

200 Generation completed. Inspect `success` and `valid` to determine whether usable KQL was produced. The request succeeded and the response body contains the requested data.

Response Body Parameters

EdxAiGenerateResponseV202606

Property	Description	Type
attempts		integer (int32)
clarificationOptions		string[]
clarificationQuestion		string
error		string
errors		string[]
explanation		string
kql		string
requiresClarification	True when the model needs the user to disambiguate a referenced entity (no KQL yet). The UI presents EnergyCap.DTO.V202606.EdxAiGenerateResponse.ClarificationOptions and re-asks with the chosen value.	boolean
resolutionSteps	Human-readable trace of the entity-resolution lookups the model ran behind the scenes, surfaced for transparency. Empty for a straightforward single-shot generation.	string[]
success		boolean
valid		boolean

Example Response application/json

{  "attempts": 1,  "clarificationOptions": [
    "string"
  ],  "clarificationQuestion": "string",  "error": "string",  "errors": [
    "string"
  ],  "explanation": "string",  "kql": "string",  "requiresClarification": false,  "resolutionSteps": [
    "string"
  ],  "success": false,  "valid": false
}