Skip to main content

Build Report Definition With AI

POST 
/api/v2/report-builder/ai-build

Generate a builder report definition from a plain-English request using the AI assistant configured for your account. The definition is checked against the report schema (with one automatic retry) before it is returned; nothing is saved — run it with Run Ad-Hoc Report or save it with Create Custom Report.

Required scope: reports:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Body:

  • prompt (string, required, max 2000): what you want, e.g. "top 10 SKUs by net revenue last quarter"
  • current_domain (string, optional, max 100) and current_base_entity (string, optional, max 100): hints for where to start
  • history (array, optional, max 20): earlier turns of the conversation, each {role: user|assistant, content} (content max 4000); only the last 10 are used
  • current_definition (object, optional): the draft to refine instead of starting over
  • last_error (string, optional, max 2000): an error you saw when running the previous draft

Response: definition and a short explanation. Returns 422 with a message when the AI assistant is disabled, no API key is configured, or no valid definition could be produced.

Authentication: Bearer token (Personal Access Token). Personal access tokens need the reports:write scope.

Request​

Responses​

OK

Response Headers
    Content-Type