Skip to main content
PATCH
/
v2
/
documents
/
{documentId}
/
draft
curl --request PATCH \
  --url https://{instance}.omniapp.co/api/v2/documents/{documentId}/draft \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Q2 Revenue (final)",
  "summary": "Rename and enable cross-filtering",
  "settings": {
    "crossfilterEnabled": true
  }
}
'
{
  "identifier": "q2-revenue",
  "draftIdentifier": "q2-revenue-draft-7f3a",
  "name": "Q2 Revenue (final)",
  "description": "Quarterly revenue review"
}

​
Draft → publish workflow

Editing an existing document is a three-step flow:
  1. PATCH /api/v2/documents/{documentId}/draft (this endpoint) — creates a new draft on the published document and applies your patch. Returns the new draftIdentifier.
  2. (optional) PATCH /api/v2/documents/{documentId}/draft/{draftId} — apply further patches to that draft.
  3. POST /api/v2/documents/{documentId}/draft/publish — publish the main draft live.
A document may have only one main draft at a time. If one already exists, this endpoint returns 409 — patch the existing draft (step 2) or publish/discard it first. This replaces v1’s clearExistingDraft flag, which does not exist in v2. A GET response is a valid PATCH body — read the current state, edit it, and submit it back verbatim.

​
Field constraints

FieldLimitError (400)
name (document)1–254 charactersname cannot be empty · name must be 254 characters or fewer
summary1–255 characters, optionalsummary cannot be empty · summary must be 255 characters or fewer
queryPresentations.data.{key}.name1–144 charactersname must be 144 characters or fewer
queryPresentations.data.{key}.subTitle≤ 250 characterssubTitle must be 250 characters or fewer
queryPresentations.data.{key}.description≤ 500 charactersdescription must be 500 characters or fewer
queryPresentations.data≤ 48 non-null entries per patchA single patch may carry at most 48 query presentations.
summary is an audit-trail note describing the change (never returned by reads); when omitted the server generates one from the touched sections. Null queryPresentations.data entries (deletions) do not count toward the 48-entry cap.

​
Addressing tiles (no miniUuid)

Tiles are addressed by their record key in queryPresentations.data (e.g. "2"). The server owns internal tile identity, so you never send or manage miniUuid:
  • New key → a new tile is created.
  • Existing key, identical content (a verbatim round-trip of a GET) → treated as a no-op and dropped from the patch.
  • Existing key, changed content → the tile is updated (the server regenerates its internal identifier).
  • linked-type tabs always re-resolve — they are excluded from no-op detection.
  • Query presentations are immutable server-side: replace a tile by key, don’t mutate it in place.
data is shallow-merged by key — omitted keys are untouched; data.{key}: null deletes that tile. order, when present, replaces the tab order. controls and settings are likewise shallow-merged; containers, when present, fully replaces the layout.

​
AI summaries via linked tiles

There is no narrative field. To attach an AI-style summary that reuses another tile’s query, add a linked-type query presentation whose sourceQueryPresentationKey points at the source tile’s record key (a string such as "2" — not a positional index into order): 
{
  "queryPresentations": {
    "data": {
      "3": {
        "type": "linked",
        "name": "Summary",
        "sourceQueryPresentationKey": "2"
      }
    }
  }
}

Authorizations

​
Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Path Parameters

​
documentId
string
required

The published document's URL slug (e.g. abc123) or its canonical workbook UUID.

Body

application/json

The draft-route patch body plus an optional branchId selecting the branch the new draft is attached to.

​
branchId
string<uuid>

Branch the draft is created on. Omit for a draft on the main (unpublished) workspace.

​
name
string

Document name.

Required string length: 1 - 254
​
description
string | null

Document description.

​
summary
string

Caller-supplied description of what this patch changes, written to the history audit trail. When absent, the server generates one from the touched sections.

Required string length: 1 - 255
​
queryPresentations
object

Query presentations (tabs/tiles) keyed by record key.

​
controls
object

Dashboard filters/controls keyed by control ID.

​
settings
object

Document settings. Shallow-merged with the existing settings.

​
containers
object[]

Container layout. When present, fully replaces the existing layout.

Response

Draft created and patch applied successfully.

​
identifier
string
required

Published document identifier the draft targets.

​
draftIdentifier
string
required

Identifier of the draft the patch was applied to.

​
name
string
required

Document name.

​
description
string | null
required

Document description.