---
title: "Create draft and patch document"
method: PATCH
path: "/v2/documents/{documentId}/draft"
tags: ["Documents v2"]
---

# Create draft and patch document

`PATCH /v2/documents/{documentId}/draft`

Create a new draft on the published document and apply the patch. There is no auto-publish — the response includes the new `draftIdentifier` for follow-up calls. Pass an optional `branchId` to attach the draft to a branch; omit it for a draft on the main (unpublished) workspace.

## Path parameters

- `documentId` string, required

## Request body

- DocumentsV2CreateDraftBody — 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.
  - `description` string, nullable — 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.
  - `queryPresentations` DocumentsV2QueryPresentationsPatch — Query presentations (tabs/tiles) keyed by record key.
    - `data` object — Tabs keyed by record key (a positive-integer string, e.g. `"1"`, `"2"`). Shallow-merged by key — omitted keys are untouched; set a key to `null` to delete that tab. Capped at 48 non-null entries per patch.
    - `order` string[] — Tab display order. When present, replaces the existing order.
  - `controls` DocumentsV2ControlsPatch — Dashboard filters/controls keyed by control ID.
    - `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.
  - `settings` DocumentsV2SettingsPatch — 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.
      - `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.
  - `containers` object[] — Container layout. When present, fully replaces the existing layout.

## Response `200`

Draft created and patch applied successfully.

- DocumentsV2PatchDraftResponse
  - `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, nullable, required — Document description.

## Other responses

- `400` — Invalid request body or schema validation error — for example an unknown top-level field, a length cap exceeded, or the query-presentation cap exceeded (`A single patch may carry at most 48 query presentations.`). Also returned when `modelId` doesn't match the document's current base model.
- `401` — Authentication required.
- `403` — Insufficient permissions to update the document.
- `404` — Document or branch not found.
- `405` — Method Not Allowed - Invalid HTTP method for this endpoint
- `409` — The target is not a published document (drafts only attach to published documents) — for example a draft already exists for this document — or a concurrent request just created its layout; retry.
- `422` — The document cannot satisfy the patch: a classic-layout dashboard (upgrade to the advanced layout first), an app document, or a workbook-only document patched without a `containers` payload (or with an empty one).

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/versions/6b02f7349d0e/schema)