--- title: "Read draft state" method: GET path: "/api/v2/documents/{identifier}/draft/{draftIdentifier}" tags: ["Documents"] --- # Read draft state `GET /api/v2/documents/{identifier}/draft/{draftIdentifier}` Read the named draft's state. Returns the full `DocumentsV2ReadResponse` shape — same as the live-state read endpoint. The response is structured so a caller can take it verbatim and submit it as the body of the draft PATCH routes. Tiles in `queryPresentations.data` are keyed by a stable record key (e.g. `"1"`, `"2"`) — the server uses that key to identify existing tiles for updates, so callers do not need to track or send any other identifier. Control IDs and container `instanceKey` / `referenceKey` values also round-trip unchanged. ## Path parameters - `draftIdentifier` string, required — Draft workbook identifier (see `PATCH /api/v2/documents/{identifier}/draft`). - `identifier` string, required — Published document identifier. ## Query parameters - `pretty` '0' | '1' | 'true' | 'false' — Set `true` or `1` to pretty-print (2-space indent) the response; `false` / `0` (the default) is compact. Key ordering is deterministic regardless. ## Response `200` Draft state. - DocumentsV2ReadResponse - `containers` union[] — Container layout array (grid / stack / page / reference containers, recursively nested). The server validates the full structure on apply. - union - GridContainer — Grid container — children are positioned on a grid (each carries a gridPosition). - `description` string — Optional description for the container, providing additional context or information - `instanceKey` string, required — Unique identifier for this container. Used to reference the container when adding, moving, or removing children. - `name` string — Human-readable name for the container, used for easier reference in logic and design - `aspectRatio` string - `fillSpace` boolean - `height` string - `maxHeight` string - `maxWidth` string - `minHeight` string - `minWidth` string - `width` string - `after` union - StackContainer — Stack container — an ordered list of nested children (content, grid, stack, or reference). - `description` string — Optional description for the container, providing additional context or information - `instanceKey` string, required — Unique identifier for this container. Used to reference the container when adding, moving, or removing children. - `name` string — Human-readable name for the container, used for easier reference in logic and design - `aspectRatio` string - `fillSpace` boolean - `height` string - `maxHeight` string - `maxWidth` string - `minHeight` string - `minWidth` string - `width` string - `after` union - … - `align` 'flex-start' | 'flex-end' | 'center' | 'stretch' — Cross-axis alignment of children (e.g., center, stretch) - `before` union - … - `children` union[], required - … - `containerType` 'stack', required — Stack containers lay out children sequentially in a direction (column or row) - `direction` 'column' | 'row' — Layout direction: "row" lays out horizontally, "column" stacks vertically (default if not specified) - `gap` union — Space between children (CSS size value) - … - `justify` 'flex-start' | 'flex-end' | 'center' | 'space-between' — Main-axis alignment of children (e.g., start, center, end) - `metadata` object — Optional bookkeeping for this container (e.g. `attachedQueryKey` for auto-placed tiles) - … - `mobileBehavior` 'stack' | 'wrap' | 'keep' | 'hide' — Overrides the automatic mobile layout: "stack" flips a row to a column, "wrap" keeps the row and wraps items, "keep" freezes the desktop arrangement, "hide" hides the container on mobile - `padding` union - … - `style` string - `wrap` 'nowrap' | 'wrap' — Whether flex items should wrap to new lines (defaults to nowrap if not specified) - ReferenceContainer — Reference container — points at another container in the collection by its instanceKey. - `containerType` 'reference', required - `instanceKey` string, required - `referenceKey` string, required - `before` union - StackContainer — Stack container — an ordered list of nested children (content, grid, stack, or reference). - `description` string — Optional description for the container, providing additional context or information - `instanceKey` string, required — Unique identifier for this container. Used to reference the container when adding, moving, or removing children. - `name` string — Human-readable name for the container, used for easier reference in logic and design - `aspectRatio` string - `fillSpace` boolean - `height` string - `maxHeight` string - `maxWidth` string - `minHeight` string - `minWidth` string - `width` string - `after` union - … - `align` 'flex-start' | 'flex-end' | 'center' | 'stretch' — Cross-axis alignment of children (e.g., center, stretch) - `before` union - … - `children` union[], required - … - `containerType` 'stack', required — Stack containers lay out children sequentially in a direction (column or row) - `direction` 'column' | 'row' — Layout direction: "row" lays out horizontally, "column" stacks vertically (default if not specified) - `gap` union — Space between children (CSS size value) - … - `justify` 'flex-start' | 'flex-end' | 'center' | 'space-between' — Main-axis alignment of children (e.g., start, center, end) - `metadata` object — Optional bookkeeping for this container (e.g. `attachedQueryKey` for auto-placed tiles) - … - `mobileBehavior` 'stack' | 'wrap' | 'keep' | 'hide' — Overrides the automatic mobile layout: "stack" flips a row to a column, "wrap" keeps the row and wraps items, "keep" freezes the desktop arrangement, "hide" hides the container on mobile - `padding` union - … - `style` string - `wrap` 'nowrap' | 'wrap' — Whether flex items should wrap to new lines (defaults to nowrap if not specified) - ReferenceContainer — Reference container — points at another container in the collection by its instanceKey. - `containerType` 'reference', required - `instanceKey` string, required - `referenceKey` string, required - `children` union[], required - union - object — Reference container — points at another container in the collection by its instanceKey. - … - object — Stack container — an ordered list of nested children (content, grid, stack, or reference). - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - `containerType` 'grid', required - `gridPosition` object - `h` integer, required — Height in grid units (default: 36 for charts) - `w` integer, required — Width in grid columns on a 24-column grid. Common widths: 24 (full), 12 (half), 8 (third), 6 (quarter). x + w must not exceed 24. - `x` integer, required — X position on a 24-column grid (0=left edge, 12=middle). Items side-by-side share the same y with complementary x values. - `y` integer, required — Y position in grid units (0=top, higher values=lower on page) - `metadata` object — Optional bookkeeping for this container (e.g. `attachedQueryKey` for auto-placed tiles) - `attachedQueryKey` string — Set by the auto-add-tile flow when this container was generated for a specific workbook tab. The server removes containers with a matching `attachedQueryKey` when that tab is deleted. The reducer clears this when the user adds unrelated content (a different query, filter, text tile, page switcher, or sub-container). - `generatedHeading` boolean — Marks the auto-injected heading wrapper (title + description row) created for a tile, so it can be labeled generically and treated as managed. - `locked` boolean — Locks the container's internal arrangement so its children cannot be dragged, reordered, resized, or have new items dropped in. Cascades to all descendants. Does not lock the container's own position/size. - `mobileBehavior` 'stack' | 'wrap' | 'keep' | 'hide' — Overrides the automatic mobile layout: "keep" freezes the desktop grid arrangement, "hide" hides the container on mobile ("stack" and "wrap" apply to row stacks) - `padding` union - 0 - 0.5 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - `style` string - PageContainer — Page container — a top-level page wrapping a single grid, stack, or reference container, optionally per breakpoint/media. - `description` string — Optional description for the container, providing additional context or information - `instanceKey` string, required — Unique identifier for this container. Used to reference the container when adding, moving, or removing children. - `name` string — Human-readable name for the container, used for easier reference in logic and design - `breakpoint` 'desktop' | 'mobile' - `container` union, required - GridContainer — Grid container — children are positioned on a grid (each carries a gridPosition). - `description` string — Optional description for the container, providing additional context or information - `instanceKey` string, required — Unique identifier for this container. Used to reference the container when adding, moving, or removing children. - `name` string — Human-readable name for the container, used for easier reference in logic and design - `aspectRatio` string - `fillSpace` boolean - `height` string - `maxHeight` string - `maxWidth` string - `minHeight` string - `minWidth` string - `width` string - `after` union - … - `before` union - … - `children` union[], required - … - `containerType` 'grid', required - `gridPosition` object - … - `metadata` object — Optional bookkeeping for this container (e.g. `attachedQueryKey` for auto-placed tiles) - … - `mobileBehavior` 'stack' | 'wrap' | 'keep' | 'hide' — Overrides the automatic mobile layout: "keep" freezes the desktop grid arrangement, "hide" hides the container on mobile ("stack" and "wrap" apply to row stacks) - `padding` union - … - `style` string - StackContainer — Stack container — an ordered list of nested children (content, grid, stack, or reference). - `description` string — Optional description for the container, providing additional context or information - `instanceKey` string, required — Unique identifier for this container. Used to reference the container when adding, moving, or removing children. - `name` string — Human-readable name for the container, used for easier reference in logic and design - `aspectRatio` string - `fillSpace` boolean - `height` string - `maxHeight` string - `maxWidth` string - `minHeight` string - `minWidth` string - `width` string - `after` union - … - `align` 'flex-start' | 'flex-end' | 'center' | 'stretch' — Cross-axis alignment of children (e.g., center, stretch) - `before` union - … - `children` union[], required - … - `containerType` 'stack', required — Stack containers lay out children sequentially in a direction (column or row) - `direction` 'column' | 'row' — Layout direction: "row" lays out horizontally, "column" stacks vertically (default if not specified) - `gap` union — Space between children (CSS size value) - … - `justify` 'flex-start' | 'flex-end' | 'center' | 'space-between' — Main-axis alignment of children (e.g., start, center, end) - `metadata` object — Optional bookkeeping for this container (e.g. `attachedQueryKey` for auto-placed tiles) - … - `mobileBehavior` 'stack' | 'wrap' | 'keep' | 'hide' — Overrides the automatic mobile layout: "stack" flips a row to a column, "wrap" keeps the row and wraps items, "keep" freezes the desktop arrangement, "hide" hides the container on mobile - `padding` union - … - `style` string - `wrap` 'nowrap' | 'wrap' — Whether flex items should wrap to new lines (defaults to nowrap if not specified) - ReferenceContainer — Reference container — points at another container in the collection by its instanceKey. - `containerType` 'reference', required - `instanceKey` string, required - `referenceKey` string, required - `containerType` 'page', required - `media` 'screen' | 'print' - StackContainer — Stack container — an ordered list of nested children (content, grid, stack, or reference). - `description` string — Optional description for the container, providing additional context or information - `instanceKey` string, required — Unique identifier for this container. Used to reference the container when adding, moving, or removing children. - `name` string — Human-readable name for the container, used for easier reference in logic and design - `aspectRatio` string - `fillSpace` boolean - `height` string - `maxHeight` string - `maxWidth` string - `minHeight` string - `minWidth` string - `width` string - `after` union - StackContainer — recursive - ReferenceContainer — Reference container — points at another container in the collection by its instanceKey. - `containerType` 'reference', required - `instanceKey` string, required - `referenceKey` string, required - `align` 'flex-start' | 'flex-end' | 'center' | 'stretch' — Cross-axis alignment of children (e.g., center, stretch) - `before` union - StackContainer — recursive - ReferenceContainer — Reference container — points at another container in the collection by its instanceKey. - `containerType` 'reference', required - `instanceKey` string, required - `referenceKey` string, required - `children` union[], required - union - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - object - … - ReferenceContainer — Reference container — points at another container in the collection by its instanceKey. - … - GridContainer — Grid container — children are positioned on a grid (each carries a gridPosition). - … - StackContainer — recursive - `containerType` 'stack', required — Stack containers lay out children sequentially in a direction (column or row) - `direction` 'column' | 'row' — Layout direction: "row" lays out horizontally, "column" stacks vertically (default if not specified) - `gap` union — Space between children (CSS size value) - 0 - 0.5 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 - 16 - `justify` 'flex-start' | 'flex-end' | 'center' | 'space-between' — Main-axis alignment of children (e.g., start, center, end) - `metadata` object — Optional bookkeeping for this container (e.g. `attachedQueryKey` for auto-placed tiles) - `attachedQueryKey` string — Set by the auto-add-tile flow when this container was generated for a specific workbook tab. The server removes containers with a matching `attachedQueryKey` when that tab is deleted. The reducer clears this when the user adds unrelated content (a different query, filter, text tile, page switcher, or sub-container). - `generatedHeading` boolean — Marks the auto-injected heading wrapper (title + description row) created for a tile, so it can be labeled generically and treated as managed. - `locked` boolean — Locks the container's internal arrangement so its children cannot be dragged, reordered, resized, or have new items dropped in. Cascades to all descendants. Does not lock the container's own position/size. - `mobileBehavior` 'stack' | 'wrap' | 'keep' | 'hide' — Overrides the automatic mobile layout: "stack" flips a row to a column, "wrap" keeps the row and wraps items, "keep" freezes the desktop arrangement, "hide" hides the container on mobile - `padding` union - 0 - 0.5 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - `style` string - `wrap` 'nowrap' | 'wrap' — Whether flex items should wrap to new lines (defaults to nowrap if not specified) - `controls` ControlsReadExternal - `data` object, required — Controls keyed by control ID. - `order` string[], required — Display order for controls. - `description` string, nullable, required — Document description. - `modelId` string, uuid, required — Base model the document is built on (the `modelId` supplied at create). Immutable — echoed here so a GET round-trips through PATCH; supplying a different value on PATCH is rejected. - `name` string, required — Document name. - `queryPresentations` QueryPresentationsReadExternal, required - `data` object, required — Query presentations keyed by tab ID. A FOREIGN tab — one whose query runs against a shared model other than this document’s — carries its execution model at `foreignModelId`. - `order` string[], required — Tab display order. - `settings` SettingsReadExternal - `crossfilterEnabled` boolean, required — When true, clicking a value in one tile filters all other tiles on the dashboard. - `customText` object, nullable, required — Custom text replacing default UI strings on the dashboard, e.g. when queries error or return no results. - `queryError` string — Custom text shown when a query errors, replacing the default error text. - `queryNoResults` string — Custom text shown when a query returns no results, replacing the default empty state. - `facetFilters` boolean, required — When true, dashboard filters are applied per-facet when faceting is active. - `refreshInterval` number, nullable, required — Auto-refresh interval in seconds. Null disables auto-refresh. - `runQueriesOn` 'current-page' | 'all-pages' | 'null', nullable, required — Controls whether dashboard queries execute on the visible page or across all pages. - `workbookModelId` string, uuid, required — Server-assigned WORKBOOK-layer model layered on `modelId`. Read-only — echoed here so a GET round-trips through PATCH; each draft has its own, so a draft read returns the draft workbook’s model. ## Other responses - `401` — Authentication required. - `403` — Insufficient permissions to read the draft. - `404` — Document or draft not found. - `422` — The draft cannot be read as a dashboard: a classic-layout dashboard (upgrade to the advanced layout first) or an app document. --- [API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/versions/de7cac8b5983/schema)