---
title: "Draft Overview dashboard widgets from a natural-language request"
method: POST
path: "/overview/widget-drafts"
---

# Draft Overview dashboard widgets from a natural-language request

`POST /overview/widget-drafts`

Drafts 1-6 widgets (exactly 1 when editWidget is set) in the shape the widget editor saves. Filter values are grounded in the organization's own data and every widget is re-validated against the frontend widget rules; widgets that fail are dropped with a warning. Nothing is persisted. Requires org.edit_dashboard. Billed as AI usage under the overview_dashboard feature area (operation widget_draft); a fallback draft is recorded but not charged.

## Request body

- OverviewWidgetDraftRequest
  - `currentFilters` object, required
    - `endDate` string, required — Dashboard range end month (YYYY-MM).
    - `startDate` string, required — Dashboard range start month (YYYY-MM).
  - `editWidget` object — The widget to change (a SaveWidgetPayload). When present, exactly one widget comes back: this one with the requested change applied.
  - `existingWidgets` object[] — Widgets already on the dashboard, so the draft does not repeat them.
    - `title` string, required
    - `type` string, required
  - `prompt` string, required
  - `requestId` string, uuid — The frontend's own id for this request. Send it to be able to stop the draft with POST /overview/widget-drafts/{requestId}/cancel.

## Response `200`

Validated widget drafts

- OverviewWidgetDraftResponse
  - `data` OverviewWidgetDraftResult, required
    - `creditsCharged` integer, required
    - `draftId` string, required
    - `fallback` boolean, required — True when the model's answer was unusable and the widgets come from a keyword planner (or, when editing, are the unchanged widget).
    - `message` string, required — One or two plain-language sentences about what was drafted.
    - `mode` 'create' | 'edit', required
    - `warnings` string[], required — Plain-language notes on every repair or removal.
    - `widgets` OverviewDraftWidget[], required
      - `columnTracks` boolean
      - `comparison` object
        - `mode` 'side-by-side' | 'overlay', required
        - `monthFrom` integer, required
        - `monthTo` integer, required
        - `yearA` integer, required
        - `yearB` integer, required
      - `description` string
      - `dimensionSegment` 'month' | 'year'
      - `kpiDenominator` object
        - `label` string, required
        - `value` number, required
      - `kpiSparkline` boolean
      - `measures` OverviewDraftWidgetMeasure[]
        - `baseParameter` 'emission' | 'raw' | 'spend', required
        - `calculationMode` 'aggregation', required
        - `filters` OverviewDraftWidgetFilter[], required
          - `field` 'factor_scope' | 'factor_region' | 'factor_category' | 'activity_unit' | 'spend_currency' | 'supplier' | 'supplier_country' | 'supplier_risk', required
          - `id` string, required
          - `operator` 'is' | 'is-not' | 'including' | 'not-including' | 'is-empty' | 'is-not-empty', required
          - `value` string
          - `values` string[]
        - `groupBy` 'none' | 'factor_scope' | 'factor_region' | 'factor_category' | 'supplier' | 'supplier_country' | 'supplier_risk', required
        - `measureName` string, required
        - `method` 'sum' | 'avg' | 'max' | 'min' | 'count', required
      - `supplierMetric` 'top-emitters' | 'by-risk' | 'by-country' | 'by-sector' | 'high-risk-count'
      - `title` string, required
      - `totalLine` boolean
      - `type` 'kpi-card' | 'column' | 'bar' | 'line' | 'area' | 'pie' | 'progress' | 'table' | 'factors-table', required
      - `visibleFields` string[]

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Not enough AI credits, or AI usage is paused for the account
- `403` — Forbidden
- `422` — The gateway answered but no drafted widget passed validation
- `502` — The AI gateway failed or returned an invalid payload
- `503` — Widget drafting is not configured
- `504` — The AI gateway timed out

## Changes

- **2026-10-01** `b4751fd15397` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greentally/apis/esgai-api/changes/overview/widget-drafts/post.md)

---

[API](https://skmtc.dev/greentally/apis/esgai-api.md) · [All operations](https://skmtc.dev/greentally/apis/esgai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greentally/apis/esgai-api/revisions/b4751fd15397?raw)