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

import requests

url = "https://{instance}.omniapp.co/api/v1/documents/{documentId}"

payload = {
    "modelId": "abc123",
    "name": "Monthly Sales Dashboard",
    "description": "Total monthly sales. Used in sales review meetings.",
    "facetFilters": True,
    "refreshInterval": None,
    "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
            } } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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}}}
  })
};

fetch('https://{instance}.omniapp.co/api/v1/documents/{documentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{instance}.omniapp.co/api/v1/documents/{documentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    '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
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{instance}.omniapp.co/api/v1/documents/{documentId}"

	payload := strings.NewReader("{\n  \"modelId\": \"abc123\",\n  \"name\": \"Monthly Sales Dashboard\",\n  \"description\": \"Total monthly sales. Used in sales review meetings.\",\n  \"facetFilters\": true,\n  \"refreshInterval\": null,\n  \"filterConfig\": {\n    \"order_items.category\": {\n      \"type\": \"string\",\n      \"kind\": \"EQUALS\",\n      \"values\": [\n        \"Electronics\"\n      ],\n      \"is_negative\": false\n    }\n  },\n  \"filterOrder\": [\n    \"order_items.category\"\n  ],\n  \"queryPresentations\": [\n    {\n      \"name\": \"Sales Trend\",\n      \"description\": \"Monthly sales over time\",\n      \"prefersChart\": true,\n      \"topicName\": \"order_items\",\n      \"query\": {\n        \"fields\": [\n          \"order_items.created_at[month]\",\n          \"order_items.sale_price_sum\"\n        ],\n        \"table\": \"order_items\"\n      },\n      \"visConfig\": {\n        \"visType\": \"basic\",\n        \"spec\": {\n          \"mark\": {\n            \"type\": \"line\"\n          }\n        }\n      }\n    }\n  ],\n  \"documentMetadata\": {\n    \"presentation\": {\n      \"filters\": {\n        \"collapsible\": true,\n        \"defaultExpanded\": false\n      }\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://{instance}.omniapp.co/api/v1/documents/{documentId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"modelId\": \"abc123\",\n  \"name\": \"Monthly Sales Dashboard\",\n  \"description\": \"Total monthly sales. Used in sales review meetings.\",\n  \"facetFilters\": true,\n  \"refreshInterval\": null,\n  \"filterConfig\": {\n    \"order_items.category\": {\n      \"type\": \"string\",\n      \"kind\": \"EQUALS\",\n      \"values\": [\n        \"Electronics\"\n      ],\n      \"is_negative\": false\n    }\n  },\n  \"filterOrder\": [\n    \"order_items.category\"\n  ],\n  \"queryPresentations\": [\n    {\n      \"name\": \"Sales Trend\",\n      \"description\": \"Monthly sales over time\",\n      \"prefersChart\": true,\n      \"topicName\": \"order_items\",\n      \"query\": {\n        \"fields\": [\n          \"order_items.created_at[month]\",\n          \"order_items.sale_price_sum\"\n        ],\n        \"table\": \"order_items\"\n      },\n      \"visConfig\": {\n        \"visType\": \"basic\",\n        \"spec\": {\n          \"mark\": {\n            \"type\": \"line\"\n          }\n        }\n      }\n    }\n  ],\n  \"documentMetadata\": {\n    \"presentation\": {\n      \"filters\": {\n        \"collapsible\": true,\n        \"defaultExpanded\": false\n      }\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.omniapp.co/api/v1/documents/{documentId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"modelId\": \"abc123\",\n  \"name\": \"Monthly Sales Dashboard\",\n  \"description\": \"Total monthly sales. Used in sales review meetings.\",\n  \"facetFilters\": true,\n  \"refreshInterval\": null,\n  \"filterConfig\": {\n    \"order_items.category\": {\n      \"type\": \"string\",\n      \"kind\": \"EQUALS\",\n      \"values\": [\n        \"Electronics\"\n      ],\n      \"is_negative\": false\n    }\n  },\n  \"filterOrder\": [\n    \"order_items.category\"\n  ],\n  \"queryPresentations\": [\n    {\n      \"name\": \"Sales Trend\",\n      \"description\": \"Monthly sales over time\",\n      \"prefersChart\": true,\n      \"topicName\": \"order_items\",\n      \"query\": {\n        \"fields\": [\n          \"order_items.created_at[month]\",\n          \"order_items.sale_price_sum\"\n        ],\n        \"table\": \"order_items\"\n      },\n      \"visConfig\": {\n        \"visType\": \"basic\",\n        \"spec\": {\n          \"mark\": {\n            \"type\": \"line\"\n          }\n        }\n      }\n    }\n  ],\n  \"documentMetadata\": {\n    \"presentation\": {\n      \"filters\": {\n        \"collapsible\": true,\n        \"defaultExpanded\": false\n      }\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

PUT

documents

{documentId}

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

import requests

url = "https://{instance}.omniapp.co/api/v1/documents/{documentId}"

payload = {
    "modelId": "abc123",
    "name": "Monthly Sales Dashboard",
    "description": "Total monthly sales. Used in sales review meetings.",
    "facetFilters": True,
    "refreshInterval": None,
    "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
            } } }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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}}}
  })
};

fetch('https://{instance}.omniapp.co/api/v1/documents/{documentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{instance}.omniapp.co/api/v1/documents/{documentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    '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
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{instance}.omniapp.co/api/v1/documents/{documentId}"

	payload := strings.NewReader("{\n  \"modelId\": \"abc123\",\n  \"name\": \"Monthly Sales Dashboard\",\n  \"description\": \"Total monthly sales. Used in sales review meetings.\",\n  \"facetFilters\": true,\n  \"refreshInterval\": null,\n  \"filterConfig\": {\n    \"order_items.category\": {\n      \"type\": \"string\",\n      \"kind\": \"EQUALS\",\n      \"values\": [\n        \"Electronics\"\n      ],\n      \"is_negative\": false\n    }\n  },\n  \"filterOrder\": [\n    \"order_items.category\"\n  ],\n  \"queryPresentations\": [\n    {\n      \"name\": \"Sales Trend\",\n      \"description\": \"Monthly sales over time\",\n      \"prefersChart\": true,\n      \"topicName\": \"order_items\",\n      \"query\": {\n        \"fields\": [\n          \"order_items.created_at[month]\",\n          \"order_items.sale_price_sum\"\n        ],\n        \"table\": \"order_items\"\n      },\n      \"visConfig\": {\n        \"visType\": \"basic\",\n        \"spec\": {\n          \"mark\": {\n            \"type\": \"line\"\n          }\n        }\n      }\n    }\n  ],\n  \"documentMetadata\": {\n    \"presentation\": {\n      \"filters\": {\n        \"collapsible\": true,\n        \"defaultExpanded\": false\n      }\n    }\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://{instance}.omniapp.co/api/v1/documents/{documentId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"modelId\": \"abc123\",\n  \"name\": \"Monthly Sales Dashboard\",\n  \"description\": \"Total monthly sales. Used in sales review meetings.\",\n  \"facetFilters\": true,\n  \"refreshInterval\": null,\n  \"filterConfig\": {\n    \"order_items.category\": {\n      \"type\": \"string\",\n      \"kind\": \"EQUALS\",\n      \"values\": [\n        \"Electronics\"\n      ],\n      \"is_negative\": false\n    }\n  },\n  \"filterOrder\": [\n    \"order_items.category\"\n  ],\n  \"queryPresentations\": [\n    {\n      \"name\": \"Sales Trend\",\n      \"description\": \"Monthly sales over time\",\n      \"prefersChart\": true,\n      \"topicName\": \"order_items\",\n      \"query\": {\n        \"fields\": [\n          \"order_items.created_at[month]\",\n          \"order_items.sale_price_sum\"\n        ],\n        \"table\": \"order_items\"\n      },\n      \"visConfig\": {\n        \"visType\": \"basic\",\n        \"spec\": {\n          \"mark\": {\n            \"type\": \"line\"\n          }\n        }\n      }\n    }\n  ],\n  \"documentMetadata\": {\n    \"presentation\": {\n      \"filters\": {\n        \"collapsible\": true,\n        \"defaultExpanded\": false\n      }\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.omniapp.co/api/v1/documents/{documentId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"modelId\": \"abc123\",\n  \"name\": \"Monthly Sales Dashboard\",\n  \"description\": \"Total monthly sales. Used in sales review meetings.\",\n  \"facetFilters\": true,\n  \"refreshInterval\": null,\n  \"filterConfig\": {\n    \"order_items.category\": {\n      \"type\": \"string\",\n      \"kind\": \"EQUALS\",\n      \"values\": [\n        \"Electronics\"\n      ],\n      \"is_negative\": false\n    }\n  },\n  \"filterOrder\": [\n    \"order_items.category\"\n  ],\n  \"queryPresentations\": [\n    {\n      \"name\": \"Sales Trend\",\n      \"description\": \"Monthly sales over time\",\n      \"prefersChart\": true,\n      \"topicName\": \"order_items\",\n      \"query\": {\n        \"fields\": [\n          \"order_items.created_at[month]\",\n          \"order_items.sale_price_sum\"\n        ],\n        \"table\": \"order_items\"\n      },\n      \"visConfig\": {\n        \"visType\": \"basic\",\n        \"spec\": {\n          \"mark\": {\n            \"type\": \"line\"\n          }\n        }\n      }\n    }\n  ],\n  \"documentMetadata\": {\n    \"presentation\": {\n      \"filters\": {\n        \"collapsible\": true,\n        \"defaultExpanded\": false\n      }\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

{
  "error": "<response_code>",
  "message": "<error_reason>"
}

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`

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.

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

Document updated successfully

identifier

string

The document identifier

name

string

The updated document name

description

string

The updated document description

Get dashboard document

Delete document

⌘I