---
title: "Create a dashboard (scope: dashboards:write)"
method: POST
path: "/dashboards"
---

# Create a dashboard (scope: dashboards:write)

`POST /dashboards`

## Request

- Base URL: `https://api.lochless.io/api/v1`
- URL: `https://api.lochless.io/api/v1/dashboards`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- Dashboard
  - `name` string, required
  - `widgets` Widget[]
    - `type` 'number' | 'over_time' | 'breakdown' | 'share' | 'over_time_by_group' | 'table' | 'narrative' | 'status_kpi' | 'before_after' | 'timeline' | 'quote' | 'checklist' | 'param_block', required
    - `prompt` string, required: The widget's NL subject. Untrusted free text — stored, never interpreted.
    - `title` string: Optional short heading for the card. Omit and the heading is derived from the subject. Display-only — never compiled or executed, so it cannot change what the widget computes.
    - `spec` object: Deliverable widgets only (status_kpi/timeline/checklist/...). Display-only labels, never executed.
    - `params` object
      - `metric` string
      - `dimension` string
      - `time_bucket` string
  - `dateControl` object

## Response `201`

{ id }

## Other responses

- `400`: invalid body
- `401`
- `403`
- `409`: idempotency_conflict: Idempotency-Key reused with a different body
- `429`

---

[API](https://skmtc.dev/lochless/apis/synoptic-customer-api.md) · [All operations](https://skmtc.dev/lochless/apis/synoptic-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lochless/apis/synoptic-customer-api/revisions/e6dee3956611?raw)