Update document

PUT /v1/documents/{documentId}

Update document

cURL

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",
  "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
      }
    }
  }
}
'

200

{
  "identifier": "my-dashboard",
  "name": "Q4 Sales Dashboard",
  "description": "Total monthly sales. Used in sales review meetings."
}

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

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.

Show child attributes

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

Show child attributes

description · string

Optional description of the document. Set as null to clear the description.

Maximum string length: 1024

Example:

"Total monthly sales. Used in sales review meetings."

documentMetadata · object

Document metadata for presentation settings

Show child attributes

clearExistingDraft · boolean

If true, discards any existing draft before updating.

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

Response

200

application/json

Document updated successfully

identifier · string

The document identifier

name · string

The updated document name

description · string

The updated document description