Skip to main content
PUT
/
v1
/
documents
/
{documentId}
Update document
curl --request PUT \
  --url https://{instance}.omniapp.co/api/v1/documents/{documentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "modelId": "abc123",
  "name": "Monthly Sales Dashboard",
  "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
      }
    }
  }
}
'
{
  "identifier": "my-dashboard",
  "name": "Q4 Sales Dashboard"
}
This endpoint only works with dashboard documents. Workbook-only documents are not supported.
Update a dashboard document. The update operation follows the Omni’s draft/publish workflow:
Document TypeBehavior
DraftUpdated 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

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

Document identifier

Body

application/json
modelId
string
required

Model ID for query transformation

name
string
required

Document name

Required string length: 1 - 254
facetFilters
boolean
required

When true, enable facet filters on the dashboard

refreshInterval
integer | null
required

Auto-refresh interval in seconds. Minimum value must be 60. Use null to disable.

Required range: x >= 60
filterConfig
object
required

Dashboard filter configuration. Pass {} for no filters.

Each key is a field name and the value is a filter definition object.

filterOrder
string[]
required

Order of filters in the filter bar. Pass [] if no filters.

queryPresentations
object[]
required

Array of query presentations (at least one required)

Minimum array length: 1
documentMetadata
object

Document metadata for presentation settings

clearExistingDraft
boolean

If true, discards any existing draft before updating.

Note: This parameter is required when a draft exists for the document.

Response

Document updated successfully

identifier
string

The document identifier

name
string

The updated document name