Create draft and patch document

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"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

PATCH

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"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

Draft → publish workflow

Editing an existing document is a three-step flow:

PATCH /api/v2/documents/{documentId}/draft (this endpoint) — creates a new draft on the published document and applies your patch. Returns the new draftIdentifier.
(optional) PATCH /api/v2/documents/{documentId}/draft/{draftId} — apply further patches to that draft.
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

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 patch	`A 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.

modelId

string<uuid>

Immutable model identifier. Must match the document's current base model or the API will return a 400 error.

workbookModelId

string<uuid>

Immutable model identifier. Must match the document's current workbook model or the API will return a 400 error.

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 omitted, Omni auto-generates one from the updated sections.

Required string length: 1 - 255

queryPresentations

object

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

Show child attributes

controls

object

Dashboard filters/controls keyed by control ID.

Show child attributes

settings

object

Document settings. Shallow-merged with the existing settings.

Show child attributes

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.

Example:

"def456"

draftIdentifier

string

required

Identifier of the draft the patch was applied to.

Example:

"abc123"

name

string

required

Document name.

Example:

"Blob Sales"

description

string | null

required

Document description.

Example:

"Overview of daily Blobs R Us Sales"

Create document

Patch draft

⌘I

Getting started

AI APIs

API token APIs

Connection APIs

Content APIs

Dashboard APIs

Document APIs

Folder APIs

Label APIs

Model APIs

Query APIs

Schedule APIs

Upload APIs

User APIs

User group APIs

Create draft and patch document

Draft → publish workflow

Field constraints

Addressing tiles (no `miniUuid`)

AI summaries via linked tiles

Authorizations

Path Parameters

Body

Response

​Draft → publish workflow

​Field constraints

​Addressing tiles (no miniUuid)

​AI summaries via linked tiles

Authorizations

Path Parameters

Body

Response

Draft → publish workflow

Field constraints

Addressing tiles (no `miniUuid`)

AI summaries via linked tiles