> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.omni.co/feedback
```json
{
"path": "/api/documents/update-dashboard-document",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Update dashboard document
>
This endpoint only works with dashboard documents. Workbook-only documents are not supported.
Updates a document with the specified identifier. This endpoint performs a full resource replacement — all required fields must be provided and existing query presentations are replaced entirely.
The update operation follows the Omni's [draft/publish workflow](/content/develop):
| Document Type | Behavior |
| ------------------------------------------------------------ | ----------------------------------------------------------------- |
| **Draft** | Updated directly |
| **Published (no existing draft)** | Creates draft > Updates draft > Publishes draft |
| **Published (existing draft, `clearExistingDraft: true`)** | Discards existing draft > Creates new draft > Updates > Publishes |
| **Published (existing draft, `clearExistingDraft` not set)** | Returns `409 Conflict` |
This endpoint follows Omni's draft/publish workflow. Updates to published documents create a draft, apply changes, then publish. Use the `clearExistingDraft` parameter to discard any existing draft before updating.
## OpenAPI
````yaml /api/openapi.yaml put /v1/documents/{documentId}
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: AI
description: AI-powered query generation
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Documents
description: Create, retrieve, and manage documents
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Labels
description: >
Manage labels in an organization. Labels can be applied to documents and
folders to help organize and categorize content.
**Label types:**
- **Basic labels**: Can be created and managed by any user
- **Verified labels**: Indicate curated or officially sanctioned content.
Admin-only.
- **Homepage labels**: Appear on the organization homepage. Admin-only.
- name: Folders
description: Create and organize content folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/documents/{documentId}:
put:
tags:
- Documents
summary: Update dashboard document
description: >
This endpoint only works with dashboard documents. Workbook-only documents are not supported.
Updates a document with the specified identifier. This endpoint performs
a full resource replacement — all required fields must be provided and
existing query presentations are replaced entirely.
operationId: updateDocument
parameters:
- name: documentId
in: path
required: true
schema:
type: string
description: Document identifier
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- modelId
- name
- facetFilters
- refreshInterval
- filterConfig
- filterOrder
- queryPresentations
properties:
modelId:
type: string
description: Model ID for query transformation
name:
type: string
minLength: 1
maxLength: 254
description: Document name
description:
type: string
maxLength: 1024
description: >-
Optional description of the document. Set as `null` to clear
the description.
example: Total monthly sales. Used in sales review meetings.
facetFilters:
type: boolean
description: When `true`, enable facet filters on the dashboard
refreshInterval:
oneOf:
- type: integer
minimum: 60
- type: 'null'
description: >-
Auto-refresh interval in seconds. Minimum value must be
`60`. Use `null` to disable.
filterConfig:
type: object
description: >
Dashboard filter configuration. Pass `{}` for no filters.
Each key is a field name and the value is a filter
definition object.
additionalProperties:
type: object
properties:
type:
type: string
description: Field type (e.g., "string", "number")
kind:
type: string
description: Filter kind (e.g., "EQUALS", "GREATER_THAN")
values:
type: array
items: {}
description: Filter values
is_negative:
type: boolean
description: When `true`, negate the filter condition
filterOrder:
type: array
items:
type: string
description: Order of filters in the filter bar. Pass `[]` if no filters.
queryPresentations:
type: array
minItems: 1
description: Array of query presentations (at least one required)
items:
type: object
required:
- name
- query
properties:
name:
type: string
description: Name of the query tab
query:
type: object
required:
- fields
- table
properties:
fields:
type: array
items:
type: string
description: Array of field names to include in the query
table:
type: string
description: Table name for the query
description: Query definition
description:
type: string
description: Query description
subTitle:
type: string
description: Subtitle for the query
prefersChart:
type: boolean
description: When `true`, show chart by default
topicName:
type: string
description: Topic name for the query
chartType:
oneOf:
- type: string
- type: 'null'
description: Chart type (line, bar, etc.)
visConfig:
type: object
description: Full visualization configuration
resultConfig:
type: object
description: Result display configuration
aiConfig:
type: object
description: AI configuration
documentMetadata:
type: object
description: Document metadata for presentation settings
properties:
presentation:
type: object
properties:
filters:
type: object
properties:
collapsible:
type: boolean
description: Whether filters are collapsible
defaultExpanded:
type: boolean
description: Whether filters are expanded by default
clearExistingDraft:
type: boolean
description: >
If `true`, discards any existing draft before updating.
**Note**: This parameter is required when a draft exists for
the document.
example:
modelId: abc123
name: Monthly Sales Dashboard
description: Total monthly sales. Used in sales review meetings.
facetFilters: true
refreshInterval: null
filterConfig:
order_items.category:
type: string
kind: EQUALS
values:
- Electronics
is_negative: false
filterOrder:
- order_items.category
queryPresentations:
- name: Sales Trend
description: Monthly sales over time
prefersChart: true
topicName: order_items
query:
fields:
- order_items.created_at[month]
- order_items.sale_price_sum
table: order_items
visConfig:
visType: basic
spec:
mark:
type: line
documentMetadata:
presentation:
filters:
collapsible: true
defaultExpanded: false
responses:
'200':
description: Document updated successfully
content:
application/json:
schema:
type: object
properties:
identifier:
type: string
description: The document identifier
name:
type: string
description: The updated document name
description:
type: string
description: The updated document description
example:
identifier: my-dashboard
name: Q4 Sales Dashboard
description: Total monthly sales. Used in sales review meetings.
'400':
description: >
Bad Request. Possible causes:
- Missing required fields (`modelId`, `name`, `facetFilters`,
`refreshInterval`, `filterConfig`, `filterOrder`,
`queryPresentations`)
- Invalid field values (`name` too long, `refreshInterval` less than
`60`)
- Empty `queryPresentations` array (at least one required)
- Document has no dashboard (workbook-only document)
- Analysis documents (workbooks or documents without a dashboard)
are not supported
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: User has insufficient permissions to update document
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Document not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: >
Conflict. Draft already exists - set clearExistingDraft to true to
discard it and proceed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#personal-access-tokens-pat).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````