Stream Ask AI REST API

POST

/api/sites/{id}/ask-ai/events

curl --request POST \
  --url http://127.0.0.1:25737/api/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/ask-ai/events \
  --header 'Content-Type: application/json' \
  --cookie hk_token=<hk_token> \
  --data '{ "filters": [ { "type": "example", "value": "example" } ], "from": "2026-04-15", "history": [ { "content": "example", "role": "user" } ], "query": "example", "route": "example", "to": "2026-04-15" }'

Runs the same audited, session-only Ask AI workflow and streams safe Server-Sent Events for progress, answer deltas, and the final validated response. Requires a human dashboard session with site.view; API client bearer tokens and shared dashboard routes are rejected.

Authorizations

• cookieAuth

Parameters

Path Parameters

id

required

string format: uuid

Request Body^required

Media typeapplication/json

object

filters

Array<object>

object

type

required

string

value

required

string

from

string format: date

history

Array<object>

object

content

required

string

role

required

string

Allowed values: user assistant

query

required

string

route

string

to

string format: date

Responses

200

Ask AI Server-Sent Events stream

Media typetext/event-stream

object

delta_markdown

Session-only markdown answer delta. Final charts, actions, and citations are returned only on final events.

string

error

Stable non-secret error label when an in-stream failure occurs.

string

message_key

Dashboard i18n key for safe progress or error copy.

string

response

object

actions

required

Array<object>

object

format

string

Allowed values: xlsx json csv ndjson

label

required

string

target

required

string

type

required

string

Allowed values: navigate download_export

answer_markdown

required

string

charts

required

Array<object>

object

rows

required

Array<object>

object

key

additional properties

string | number | boolean | null

series

Array<object>

object

key

required

string

label

required

string

title

required

string

type

required

string

Allowed values: line bar table

x_key

string

citations

required

Array<object>

object

label

required

string

tool_call_id

required

string

run_id

required

string format: uuid

status

string

tool_call_id

Provider-assigned tool call identifier for progress events.

string

tool_name

Safe HitKeep analytics tool identifier for progress events.

string

type

required

string

Allowed values: progress delta final error

400

Invalid Ask AI request

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

403

Dashboard session required or forbidden

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

409

Ask AI unavailable

Media typeapplication/json

object

available

required

boolean

budget_exhausted

required

boolean

enabled

required

boolean

model

string

provider

string

status

required

string

Allowed values: disabled not_configured available budget_exhausted

Example

{
  "status": "disabled"
}

429

Ask AI budget exhausted

Media typeapplication/json

object

available

required

boolean

budget_exhausted

required

boolean

enabled

required

boolean

model

string

provider

string

status

required

string

Allowed values: disabled not_configured available budget_exhausted

Example

{
  "status": "disabled"
}