Skip to main content

Generate Filter Tree from Prompt

POST 
/api/ai/filter-suggestions

Translate a natural-language search request into a structured FilterTree payload that conforms to the Vue 3 datatable advanced-filter system.

Authentication: Requires Bearer token (Personal Access Token).

Rate limit: 60 requests per hour per user.

Behavior:

  • The server forwards the prompt and the page's availableFilters to OpenAI (model: gpt-4o-mini) using strict JSON Schema structured outputs.
  • The returned tree is validated server-side: any condition referencing a column that wasn't in availableFilters, an operator illegal for that column's type, or a value outside the column's lookupOptions whitelist is dropped silently.
  • If no filter conditions survive sanitization, the response is { "data": { "tree": { "conjunction": "and", "children": [] } } } and the frontend treats it as a no-op.
  • Maximum nesting depth is 2 (root + one sub-group). Deeper trees are rejected at the JSON Schema layer.

Request body:

  • prompt (string, required, 3–2000 chars) — the user's natural-language filter request.
  • pageContext (string, optional, max 200 chars) — short label for the current page (e.g. Sales Orders, Customers). Improves the LLM's column choice.
  • availableFilters (array, required, 1–200 items) — the page's AdvancedFilterConfig[] mapped to {column, label, type, allowedOperators?, lookupOptions?, group?}.
  • availableFilters[].type (string, required) — one of text, numeric, date, datetime, checkbox.
  • availableFilters[].allowedOperators (array<string>, optional) — restrict operators for this column. Defaults to the type's full vocabulary if omitted.
  • availableFilters[].lookupOptions (array, optional, max 500) — {value, title?} whitelist for select-style columns. The LLM is told it MUST pick a value from this list; the sanitizer drops conditions whose value isn't in it.

Failure modes:

  • 401 Unauthenticated — missing or invalid token.
  • 422 Validation — prompt blank, too long, or availableFilters missing/empty.
  • 429 Too Many Requests — rate limit exceeded.
  • 502 Bad Gateway — OpenAI auth failed (server's OPENAI_API_KEY invalid) or OpenAI is unreachable.
  • 503 Service Unavailable — OpenAI not configured on this environment (server has no OPENAI_API_KEY).

Cost note: Each call uses ~300–1500 tokens of gpt-4o-mini (≈ $0.001 or less). Logged metadata: user_id, prompt_length (not the prompt body), tokens, latency_ms, page_context.

Request​

Responses​

Successful response