dashboards

Create a dashboard from a spec.

Validates the spec against the dvt dashboard JSON Schema, decomposes its panels and lg-breakpoint layout into elements, and persists a new dashboard. If the spec omits id (or sets it to the all-zeros UUID placeholder 00000000-0000-0000-0000-000000000000), the server generates one and injects it into the stored spec. If id is set to an existing dashboard's id, the request fails with 409 — unless the existing dashboard's stored spec is semantically identical to the one submitted, in which case the request is treated as an idempotent replay and returns 200 with the existing dashboard (see PATCH /v1/dashboards/{id} to make an actual update instead).

post/v1/dashboards

Request

  • Base URL: http://localhost:8080
  • URL: http://localhost:8080/v1/dashboards
  • Auth: one of:
    • API key in cookie dvt_session
    • HTTP bearer

Request body

visibility'private' | 'shared' | 'public'
specobject required

The full dvt dashboard spec (meta, theme, layout, panels).

changeSummarystring

Optional human-readable note describing the dashboard being created (DVT-1426) — e.g. "Swapped revenue bar for cohort heatmap per Maria's request". Human-authored or agent-authored only: unlike PATCH's changeSummary below, dvt web never client-generates a diff-based summary here — there is no prior revision to diff against at create time, and the Save-confirmation modal that composes the client-generated summary (DVT-2686) is PATCH-only. A blank value here is simply recorded as blank. Recorded verbatim on the initial revision and surfaced verbatim in the org activity feed; never summarized or transformed. Over 280 characters is rejected with 400.

queryRolestring

Snowflake mode only (DVT-1738): pin the Snowflake role this dashboard's queries run under for every viewer, at create time — the same validation as PATCH's queryRole (you can only pin a role your own Snowflake session holds, validated live against CURRENT_AVAILABLE_ROLES(); unquoted role names only, canonicalized to upper case; reserved pseudo-roles (PUBLIC) are rejected 400; a non-held role is rejected 422 and the dashboard is NOT created). Omit (or pass an empty string) to create unpinned — each viewer's queries then run as their own default role. Outside snowflake mode the field is rejected with 400.

Response

Idempotent replay: the id already exists in this org with an identical spec; returns the existing dashboard unchanged (no new revision is created).

Changes

No recorded changes to this operation across all 1 revision of this API.