POST /api/v202608/energymanager/reporting/chat/{chatId}/message

Persists a reporting-chat exchange and generates KQL for querying report data

CreateReportChatMessageV202608 Permissions: EnergyManagerModule (View)
Use this endpoint for initial report prompts, refinements, and clarification selections. It persists the displayed user content and one assistant response but does not create or update a dynamic report. Execute successful KQL through the dynamic-report query endpoint and save explicitly through the dynamic-report endpoints.

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.

Path Parameters

Name Description Type Required
chatId Unique numeric identifier of an active reporting chat owned by the authenticated user integer (int32) Required

Request Body

WattsReportChatMessageCreate
Property Description Type
clarificationOptions Clarification options shown to the user. Null when no options were presented or this message is not a clarification response. string[]
clarificationOriginalPrompt Original user-facing prompt that produced a clarification question. Null when this message is not a clarification response. string
clarificationQuestion Clarification question shown to the user. Null when this message is not a clarification response. string
content User-facing message persisted verbatim in reporting chat history. Required string
priorKql KQL for the currently displayed report when this message refines an existing result. Null for an initial report request. string
Example Request Body application/json
{  "clarificationOptions": [
    "string"
  ],  "clarificationOriginalPrompt": "string",  "clarificationQuestion": "string",  "content": "string",  "priorKql": "string"
}

Responses

200 OK The request succeeded and the response body contains the requested data.

Response Body Parameters

WattsReportResultEvent
Property Description Type
result WattsReportChatResponse
WattsReportChatResponse properties
Property Description Type
citations The work behind the answer — queries run, API calls made, articles searched — in the order it happened. WattsChatCitationV202510[]
WattsChatCitationV202510 properties
Property Description Type
callId Identifies the citation within its turn. Stable across a reload, because the stored citations keep the order they ran in. string
chart WattsChatChartV202510
WattsChatChartV202510 properties
Property Description Type
chartType Chart kind: columnchart, barchart, linechart, piechart, and so on. string
columns Column names, in result order. WattsChatChartColumnV202510[]
WattsChatChartColumnV202510 properties
Property Description Type
dataType Logical type, used for axis formatting. string
name string
kind Optional sub-kind, such as stacked. string
rows Rows, each aligned positionally to EnergyCap.DTO.V202510.WattsChatChartDTO.Columns. array[]
truncated True when more rows matched than were carried for drawing. boolean
xColumn Explicit category (x-axis) column, when the query named one. string
yColumns Explicit value (y-axis) columns, when the query named them. string[]
detail The citable artifact itself: the KQL text, the API method and path, the search phrase, or the expression that was evaluated. string
documentationUrl Public documentation for what was called. Set for API citations; null otherwise. string
emptyReason Why a query that ran fine returned nothing. Null unless the result was empty. string
error Why the call failed, when it did. A failed call is still cited — showing what was attempted explains a thin answer better than silence. string
filters The filters the query applied, as a reader would say them. Lets an answer state what it covered without anyone reading KQL. string[]
kind One of the EnergyCap.DTO.V202510.WattsChatCitationKind values. string
queryTimeMs How long the work took, in milliseconds, when the tool reports it. integer (int64)
rowCount Rows or records returned. Null when the call failed or returned no count. integer (int32)
running Whether this call is still running. A citation is emitted when the call starts and again when it finishes, so a slow query shows what is being waited on rather than an unexplained spinner. boolean
summary A short plain-language outcome shown beside the citation, when one adds anything — for example the value a calculation produced. string
toolName Name of the tool that ran, e.g. run_kql or call_energycap_api. string
truncated True when more data matched than was returned. boolean
warnings Problems with the query worth telling the user about — a result built from an arbitrary sample, for instance. Empty when there is nothing to say. string[]
clarificationOptions The list of clarification options to be presented to the user if clarification is required string[]
clarificationQuestion The clarification question to be presented to the user if clarification is required string
error User-facing generation error. Empty when generation succeeds or requires clarification. string
explanation A message providing additional information about the report creation result string
isAnswerOnly True when the turn answered the question without producing a query. boolean
isSuccess Indicates whether the report creation was successful boolean
kql KQL generated from the user prompt. Null when generation requires clarification or fails. string
requiresClarification Indicates whether the report creation requires clarification from the user boolean
resolutionSteps The list of resolution steps to be presented to the user if clarification is required string[]
userMessageId Unique numeric identifier of the user message persisted for the prompt behind this response. integer (int32)
wattsChatMessageId Unique numeric identifier of the assistant message persisted for this response. integer (int32)
type string
Example Response application/json
{  "result": {    "citations": [
      {      "callId": "string",      "chart": {},      "detail": "string",      "documentationUrl": "string",      "emptyReason": "string",      "error": "string",      "filters": [],      "kind": "string",      "queryTimeMs": 1,      "rowCount": 1,      "running": false,      "summary": "string",      "toolName": "string",      "truncated": false,      "warnings": []
    }
    ],    "clarificationOptions": [
      "string"
    ],    "clarificationQuestion": "string",    "error": "string",    "explanation": "string",    "isAnswerOnly": false,    "isSuccess": false,    "kql": "string",    "requiresClarification": false,    "resolutionSteps": [
      "string"
    ],    "userMessageId": 1,    "wattsChatMessageId": 1
  },  "type": "string"
}
404 Not Found The requested resource was not found. Verify the ID or path is correct.