Create document
Create a brand-new document and publish it live in a single call. Accepts creation metadata (modelId, name, and optional identifier / description / folderId) plus the same content slice as the draft patch body — queryPresentations, controls, settings, and containers.
Tiles are addressed by their record key in queryPresentations.data (e.g. "1", "2"); the server owns internal tile identity, so you never send miniUuid. A new document starts with a single empty seed tile at key "1" — write to "1" (or send it as null) to replace the seed.
Because this is the first publish of brand-new content, it is not subject to the organization’s requirePullRequestToPublish policy (which gates edits to existing content).
Field constraints
| Field | Limit | Error (400) |
|---|---|---|
name (document) | 1–254 characters | name cannot be empty · name must be 254 characters or fewer |
summary | 1–255 characters, optional | summary cannot be empty · summary must be 255 characters or fewer |
queryPresentations.data.{key}.name | 1–144 characters | name must be 144 characters or fewer |
queryPresentations.data.{key}.subTitle | ≤ 250 characters | subTitle must be 250 characters or fewer |
queryPresentations.data.{key}.description | ≤ 500 characters | description must be 500 characters or fewer |
queryPresentations.data | ≤ 48 non-null entries per request | A single patch may carry at most 48 query presentations. |
summary is a note written to the document’s history audit trail; it is never returned by reads. On create it defaults to "Created document" when omitted. Null queryPresentations.data entries (deletions) do not count toward the 48-entry cap.
Content sections
queryPresentations— tabs/tiles keyed by record key.datais shallow-merged by key;order(when present) replaces the tab order.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).
Migrating from v1
The v1 one-shotPUT /api/v1/documents/{documentId} (Update dashboard document) maps to the v2 create → patch draft → publish workflow. For a brand-new document, a single POST /api/v2/documents is enough. To edit an existing document, use PATCH /api/v2/documents/{documentId}/draft then POST /api/v2/documents/{documentId}/draft/publish.
v1 PUT field | v2 location |
|---|---|
modelId | modelId (create only — not a patch field) |
name / description | name / description |
facetFilters (top-level) | settings.facetFilters |
refreshInterval (top-level) | settings.refreshInterval |
filterConfig / filterOrder | controls.data / controls.order |
documentMetadata (presentation) | settings.* / containers |
queryPresentations (array) | queryPresentations.data (keyed) + queryPresentations.order |
clearExistingDraft | Removed. A pre-existing draft now returns 409; patch that draft or publish/discard it instead. |
PATCH /api/v2/documents/{documentId}, and no narrative field — AI summaries attach as linked-type query presentations (see Create draft and patch document). Renaming via identifier is a v1-only capability (see Update document); on v2, identifier is a create-time field only.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. Defaults to "Created document" when omitted.
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.