---
title: "Create document"
method: POST
path: "/v2/documents"
tags: ["Documents v2"]
---

# Create document

`POST /v2/documents`

Create a brand-new document and publish it. Accepts creation metadata (`modelId`, `name`, and optional `identifier` / `description` / `folderId`) plus the same content slice as the draft patch body, including `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).

## Request body

- DocumentsV2CreateBody
  - `modelId` string, uuid, required — Base workbook model the document is built on — a SHARED model, or a SHARED_EXTENSION with `allowAsWorkbookBase = true`.
  - `name` string, required — Document name.
  - `identifier` string — Identifier (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.
  - `description` string, nullable — Document description.
  - `folderId` string, uuid, nullable — 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).
  - `summary` string — Caller-supplied note describing the create, written to the history audit trail. When omitted, Omni auto-fills it with `"Created document"`.
  - `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 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.

## Response `201`

Document created and published successfully.

- DocumentsV2CreateResponse
  - `identifier` string, required — Identifier of the newly created document.
  - `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 (`name must be 254 characters or fewer`), the query-presentation cap exceeded (`A single patch may carry at most 48 query presentations.`), or the `identifier` is already in use.
- `401` — Authentication required.
- `403` — Insufficient permissions to create a document on this model.
- `404` — Base model or branch not found.
- `405` — Method Not Allowed - Invalid HTTP method for this endpoint

---

[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)