---
title: "POST /sessions/{session_id}/dashboard_layout"
method: POST
path: "/sessions/{session_id}/dashboard_layout"
tags: ["sessions"]
---

# POST /sessions/{session_id}/dashboard_layout

`POST /sessions/{session_id}/dashboard_layout`

## Path parameters

- `session_id` string, uuid, required

## Request body

- UploadDashboardLayoutRequest
  - `layout` Dashboard, required — A page is the top-level container with title/description Can contain multiple dashboards with different datasets
    - `dashboards` DashboardPage[], required — One or more dashboards on this page
      - `components` DashboardComponent[], required — Components (charts) in this dashboard
        - `description` string, nullable — Description (optional, can override viz node's description)
        - `mosaic` MosaicQuerySpec
          - `bin` BinConfig
            - `as` string, required
            - `field` string, required
            - `step` number, double, required
          - `fields` object, required
          - `groupBy` string[], nullable
          - `limit` integer, nullable
          - `orderBy` string, nullable
          - `table` string, nullable — Table name - optional, derived from datasetNodeName in dashboard config
        - `node_name` string, required — Function name of the viz node that outputs the chart spec
        - `span` integer, nullable — Grid span: 1 (quarter), 2 (half), 3 (three-quarters), 4 (full width)
        - `title` string, required — Display title (overrides viz node title)
      - `controls` DashboardControl[], nullable — Control filters (dropdowns, checkboxes, ranges) for this dashboard
        - union
          - object
            - `default_value` string, nullable
            - `field` string, required
            - `id` string, required
            - `label` string, required
            - `options` ControlOption[], required
              - …
            - `type` 'dropdown', required
          - object
            - `default_value` number[], nullable
            - `field` string, required
            - `id` string, required
            - `label` string, required
            - `max` number, double, required
            - `min` number, double, required
            - `step` number, double, nullable
            - `type` 'range', required
          - object
            - `default_value` string[], nullable
            - `field` string, required
            - `id` string, required
            - `label` string, required
            - `options` ControlOption[], required
              - …
            - `type` 'checkbox', required
      - `datasetNodeName` string, nullable — Function name of the node that returns the dataset (DataFrame/Parquet). If None, no cross-filtering is available.
      - `description` string, nullable — Optional description
      - `title` string, required — Title for this dashboard section
    - `description` string, nullable — Optional page description
    - `title` string, required — Page title

## Response `200`

Successfully uploaded dashboard layout.

- WorkflowSession
  - `aborted` boolean, required
  - `chat_session_id` string, uuid, required
  - `created_at` string, date-time, nullable
  - `dag_ready` boolean, required
  - `dag_ready_at` string, date-time, nullable
  - `dashboard_layout_proto` string, binary, nullable
  - `error_message` string, nullable
  - `error_traceback` string, nullable
  - `id` string, uuid, required
  - `updated_at` string, date-time, required
  - `workflow_schedule_id` string, uuid

## Other responses

- `400` — Invalid request.
- `404` — Session not found.

## Changes

- **2026-01-21** `57ab04a36bcc` — 1 breaking, 1 warning
  - added the new required request property `layout/dashboards`
  - removed the request property `layout/components`
- **2026-01-21** `45952f7cb8cb` — 1 breaking, 1 warning
  - added the new required request property `layout/components`
  - removed the request property `layout/dashboards`
- **2026-01-20** `f0df1f89b82b` — 1 breaking, 1 warning
  - added the new required request property `layout/dashboards`
  - removed the request property `layout/components`

[Change history](https://skmtc.dev/structifyai/apis/structify/changes/sessions/:session_id/dashboard_layout/post.md)

---

[API](https://skmtc.dev/structifyai/apis/structify.md) · [All operations](https://skmtc.dev/structifyai/apis/structify/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/structifyai/structify/revisions/1364930b6980/schema)