--- title: "Create draft and patch document" method: PATCH path: "/api/v2/documents/{identifier}/draft" tags: ["Documents"] --- # Create draft and patch document `PATCH /api/v2/documents/{identifier}/draft` Create a new draft on the published document and apply the patch. No auto-publish — the response includes the new `draftIdentifier` for follow-up calls. Pass an optional `branchId` to attach the draft to a branch; omit it for a draft on the main (unpublished) workspace. ## Path parameters - `identifier` string, required — Document identifier — either the URL slug (e.g. `abc123`) or the canonical workbook UUID. ## Request body - DocumentsV2CreateDraftBody - `containers` union[] — Container layout. When present, fully replaces the existing layout and disables automatic tile placement for the request. - 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` ControlsPatchExternal - `data` object — Controls keyed by control ID. Shallow-merged by key — omitted keys are untouched; set to `null` to delete. - `order` string[] — Display order for controls. When present, replaces the existing order. - `description` string, nullable - `name` string — Document name. - `queryPresentations` QueryPresentationsPatchExternal - `data` object — Query presentations keyed by tab ID. Shallow-merged by key — omitted keys are untouched; set to `null` to delete. Capped at 48 entries per patch. When the request carries no `containers` and the document has a dashboard layout, dashboard-eligible tiles added at new keys are auto-placed on the dashboard's first page (non-renderable types such as CSV / dataset / query-view / dbt tabs are stored but not placed), and containers created by auto-placement are removed when their tile is deleted — containers placed via an explicit `containers` write are left in the layout. When `containers` is present it fully defines the layout; on a workbook-only document (no layout yet) tiles are stored without placement. - `order` string[] — Tab display order. When present, replaces the existing order. - `settings` SettingsPatchExternal — Document settings. Shallow-merged with the existing settings. - `crossfilterEnabled` boolean — When true, clicking a value in one tile filters all other tiles on the dashboard. - `customText` object, nullable — 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 — When true, dashboard filters are applied per-facet when faceting is active. - `refreshInterval` number, nullable — Auto-refresh interval in seconds. Null disables auto-refresh. - `runQueriesOn` 'current-page' | 'all-pages' | 'null', nullable — Controls whether dashboard queries execute on the visible page or across all pages. - `summary` string — Optional. Caller-supplied description of what this patch changes, written to the history audit trail. When omitted, the server auto-generates one from the touched sections. - `modelId` string, uuid — The document's base model. Immutable and accepted only so a GET response round-trips through PATCH: a value matching the current model is a no-op, and a differing value is rejected — it cannot re-base the document. Omit it to leave the model untouched. - `workbookModelId` string, uuid — The server-assigned workbook-layer model. Read-only and accepted only so a GET response round-trips through PATCH: a value from a GET of the draft or of the published document it targets is a no-op, and any other value is rejected. Omit it otherwise. - `branchId` string, uuid — Branch the draft is created on. Omit for a draft on the main (unpublished) workspace. ## Response `200` Draft created and patch applied successfully. - DocumentsV2PatchDraftResponse - `description` string, nullable, required — Document description. - `draftIdentifier` string, required — Identifier of the draft the patch was applied to. - `identifier` string, required — Published document identifier the draft targets. - `name` string, required — Document name. ## Other responses - `400` — Invalid request body or schema validation error (e.g. unknown top-level field, name too long, query presentation cap exceeded, a `modelId` that differs from the document’s immutable base model, or a `workbookModelId` that differs from the read-only value a GET returns). - `401` — Authentication required. - `403` — Insufficient permissions to update the document. - `404` — Document or branch not found. - `405` — Method not allowed. - `409` — The target is not a published document (drafts only attach to published documents), or a concurrent request just created the layout for this document — retry. - `422` — The document cannot satisfy the patch: a classic-layout dashboard (upgrade to the advanced layout first), an app document, or a workbook-only document patched without a `containers` payload (or with an empty one). --- [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/4701f292c621/schema)