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

# Create document

`POST /api/v1/documents`

## Request body

- DocumentsCreateBody
  - `branchId` string, uuid — Optional branch ID to associate the document with a model branch
  - `description` string, nullable — Document description
  - `facetFilters` boolean — Enable facet filters on the dashboard
  - `filterConfig` unknown
  - `filterOrder` string[] — Order of filters in the dashboard
  - `identifier` string — Optional document identifier. If omitted, an identifier is auto-generated. Must be unique within the organization.
  - `metadata` unknown
  - `metadataVersion` string — Dashboard metadata version (required when metadata is provided)
  - `modelId` string, required — Shared model ID to base the document on
  - `name` string, required — Document name
  - `queryPresentations` object[] — Query presentations for the document
    - `aiConfig` unknown
    - `chartType` string, nullable — Chart type
    - `description` string — Query presentation description
    - `name` string, required — Query presentation name
    - `prefersChart` boolean — Whether to prefer chart view
    - `query` object, required — Query definition
      - `fields` string[], required — Query fields
      - `table` string, required — Query table/topic
    - `resultConfig` unknown
    - `subTitle` string — Subtitle
    - `topicName` string, nullable — Topic name. Omit or pass null for raw-SQL tiles or any tile with no semantic topic.
    - `visConfig` ApiVisConfig, nullable — Visualization configuration
      - `config` object — Visualization spec (chart configuration)
      - `fields` string[], nullable — Field names used in the visualization
      - `visType` 'vegalite' | 'omni-ai-summary-markdown' | 'basic' | 'omni-kpi' | 'map' | 'omni-markdown' | 'funnel' | 'sankey' | 'single-record' | 'svg-map' | 'treemap' | 'omni-spreadsheet' | 'spreadsheet-tab' | 'summary-value' | 'omni-table' — Visualization type (e.g. basic, omni-markdown, omni-table)

## Response `201`

Document created successfully

- DocumentsCreateResponse
  - `dashboard` object, required — Created dashboard
    - `dashboardId` string, required — Dashboard ID
    - `id` string, required — Dashboard ID
  - `workbook` object, required — Created workbook
    - `documentId` string, required — Document ID (deprecated)
    - `id` string, required — Workbook ID

## Other responses

- `400` — Invalid request body
- `401` — Authentication required
- `403` — Permission denied
- `404` — Model or branch not found

---

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