---
title: "Create Widget"
method: POST
path: "/analytics/widgets"
tags: ["provider", "analytics", "analytics"]
---

# Create Widget

`POST /analytics/widgets`

Create a new dashboard widget.

## Headers

- `TENANT` string, required
- `API-KEY` string, required

## Request body

- CreateWidgetSchema — Schema for creating a new dashboard widget.
  - `dashboardId` string, required — ID of the dashboard this widget belongs to
  - `title` string, required — Title of the widget
  - `description` string, nullable — Optional description of the widget
  - `chartType` string, required — Type of chart (bar, area, donut, progress, etc.)
  - `queryConfig` QueryConfigSchema, required — Schema for query configuration.
    - `table` string, required — Table name to query
    - `fields` string[], required — List of fields to select
    - `filters` object[], nullable — Optional filters to apply
    - `aggregations` object, nullable — Optional aggregations to apply
    - `groupBy` string[], nullable — Optional fields to group by
    - `temporalGrouping` object, nullable — Optional temporal grouping for date fields
    - `orderBy` object, nullable — Optional ordering configuration
  - `chartConfig` object, nullable — Chart-specific configuration
  - `layoutPosition` object, required — Grid position and size {x, y, w, h}
  - `orderIndex` integer — Order index for widget positioning

## Response `201`

Successful Response

- DashboardWidgetSchema — Schema for dashboard widget response.
  - `id` string, required — Unique identifier for the widget
  - `dashboardId` string, required — ID of the dashboard this widget belongs to
  - `title` string, required — Title of the widget
  - `description` string, nullable — Description of the widget
  - `chartType` string, required — Type of chart
  - `queryConfig` QueryConfigSchema, required — Schema for query configuration.
    - `table` string, required — Table name to query
    - `fields` string[], required — List of fields to select
    - `filters` object[], nullable — Optional filters to apply
    - `aggregations` object, nullable — Optional aggregations to apply
    - `groupBy` string[], nullable — Optional fields to group by
    - `temporalGrouping` object, nullable — Optional temporal grouping for date fields
    - `orderBy` object, nullable — Optional ordering configuration
  - `chartConfig` object, nullable — Chart-specific configuration
  - `layoutPosition` object, required — Grid position and size
  - `isArchived` boolean, required — Whether the widget is archived
  - `orderIndex` integer, required — Order index for widget positioning
  - `createdDate` string, date-time, required — When the widget was created
  - `updatedDate` string, date-time, nullable — When the widget was last updated

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/decodahealth/apis/decoda-api.md) · [All operations](https://skmtc.dev/decodahealth/apis/decoda-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/decodahealth/decoda-api/revisions/4939a65a89d2/schema)