--- title: "Create document" method: POST path: "/api/v2/documents" tags: ["Documents"] --- # Create document `POST /api/v2/documents` Create a brand-new document and publish it live. Accepts creation metadata (`modelId`, `name`, optional `identifier` / `description` / `folderId`) plus the same content slice as the PATCH body — `queryPresentations`, `controls`, `settings`, `containers`. The server mints internal tile identifiers, so callers omit `miniUuid`. Tiles in `queryPresentations` are merged by key over the single empty seed tile at key `"1"`; write to `"1"` (or send it as `null`) to replace the seed. When `containers` is omitted, every dashboard-eligible tile is auto-placed in a default layout. When `containers` is present, it fully defines the layout — tiles it does not reference are stored but not rendered. Send `containers: null` to create a workbook-only document with no dashboard (`controls` and `settings` must then be omitted); an empty `containers: []` is rejected. The new document is published live before the response returns. As a first publish of brand-new content it is not subject to the org’s `requirePullRequestToPublish` policy (which gates edits to existing content). ## Request body - DocumentsV2CreateBody - `containers` union[], nullable — Container layout array, or `null` to create a workbook-only document with no dashboard. When `null`, `controls` and `settings` must be omitted. - 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 — Document description. - `folderId` string, uuid, nullable — Folder to create the document in. When omitted, defaults to the caller’s personal "My documents" (requires permission to save personal content — otherwise the request is rejected). - `identifier` string — Identifier for the new document. Must be unique within the organization. Auto-generated when omitted. - `modelId` string, uuid, required — Base workbook model the document is built on — a SHARED model, or a SHARED_EXTENSION with `allowAsWorkbookBase = true`. - `name` string, required — 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 note describing the create, written to the history audit trail. When omitted, the server auto-fills it with "Created document". ## Response `201` Document created and published successfully. - DocumentsV2CreateResponse - `description` string, nullable, required — Document description. - `identifier` string, required — Identifier of the newly created document. - `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), or the `identifier` is already in use. - `401` — Authentication required. - `403` — Insufficient permissions to create a document on this model. - `404` — Base model or branch not found. - `405` — Method not allowed. --- [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)