Create and publish document
Create and publish a brand-new document.
Because this is the first publication of brand-new content, it is not subject to the organization’s requirePullRequestToPublish policy, which gates edits to existing content.
Content sections
queryPresentations— Tabs/tiles keyed by record key inqueryPresentations.data(e.g."1","2").datais shallow-merged by key;order(when present) replaces the tab order. A new document starts with a single empty seed tile at key"1"— write to"1"or send it asnullto replace the seed.controls— Dashboard filters/controls keyed by control ID.datais shallow-merged by key (data.{id}: nulldeletes a control);order(when present) replaces the control order.settings— Dashboard settings, shallow-merged per key:crossfilterEnabled,customText(queryError/queryNoResults),facetFilters,refreshInterval,runQueriesOn.containers— The dashboard layout. When present it fully replaces the existing layout (grid / stack / page / reference containers, recursively nested).
Creating an app document
app property is currently in development and may change.app: { html, settings? } to create the document as an app instead of a dashboard. Apps must be enabled for the organization or the API will return an error. If the caller is using a PAT, the token must have permission to create apps.
app is mutually exclusive with containers (including an explicit null), controls, and settings — combining app with any of these returns a 400. queryPresentations can still be sent alongside app.
Migrating from v1
The v1 one-shotPUT /v1/documents/{documentId} maps to the v2 Create > Patch draft > Publish workflow. For a brand-new document, a single request to this endpoint is enough. To edit an existing document, use Create draft and patch document then Publish draft.
PATCH endpoint for full document updates that includes identifier changes. To rename a published document’s identifier, use the Rename document identifier endpoint.
There is also no narrative field — AI summaries attach as linked-type query presentations. See Create draft and patch document for more information.Authorizations
Can be either an Organization API Key or Personal Access Token (PAT).
Include in the Authorization header as: Bearer YOUR_TOKEN
Body
Base workbook model the document is built on — a SHARED model, or a SHARED_EXTENSION with allowAsWorkbookBase = true.
Document name.
1 - 254Identifier (URL slug) for the new document. Must be unique within the organization; auto-generated when omitted. Lowercase letters, numbers, hyphens, and underscores only; cannot start or end with a hyphen or underscore.
^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$Document description.
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).
Caller-supplied note describing the create, written to the history audit trail. When omitted, Omni auto-fills it with "Created document".
1 - 255Query presentations (tabs/tiles) keyed by record key.
Dashboard filters/controls keyed by control ID.
Document settings. Shallow-merged with the existing settings.
Container layout array (grid / stack / page / reference containers, recursively nested). On a patch, when present this fully replaces the existing layout. The server validates the full structure on apply; container instanceKey / referenceKey values round-trip unchanged. See the dashboard layout reference for the complete grammar.
Creates an app document.
Mutually exclusive with containers (including an explicit null), controls, and settings — combining app with any of these is a 400. queryPresentations can still be sent alongside app.
Response
Document created and published successfully.
Identifier of the newly created document.
Document name.
Document description.
Included only when non-blocking warnings are encountered when creating/updating an app. Currently, external resource hosts the app's iframe CSP will block until an Organization Admin allows them. The write itself succeeded.