Omni Content Builder

Create, update, and manage Omni documents and dashboards programmatically via the REST API — document lifecycle, workbook models, filters, and dashboard content.

Tip: Use omni-model-explorer to understand available fields and omni-content-explorer to find existing dashboards to modify or learn from.

Known Issues & Safe Defaults

• Chart rendering: Complex chart types may show "No chart available" in the Omni UI if config, visType, or prefersChart are misconfigured. Default to chartType: "table" for reliable rendering, and configure chart visualizations in the Omni UI.
• Every query must include at least one measure — a query with only dimensions produces empty/nonsense tiles (e.g., just months with no data).
• Use identifier not id for all document API calls — .id is null for workbook-type documents and will silently fail.
• Boolean filters may be silently dropped when a pivots array is present (reported Omni bug). If boolean filters aren't applying, remove the pivot and test again.

Prerequisites

export OMNI_BASE_URL="https://yourorg.omniapp.co"
export OMNI_API_KEY="your-api-key"

API Discovery

When unsure whether an endpoint or parameter exists, fetch the OpenAPI spec:

curl -L "$OMNI_BASE_URL/openapi.json" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Use this to verify endpoints, available parameters, and request/response schemas before making calls.

Dashboard Architecture

Omni dashboards are built from documents (workbooks). Each has:

• A dashboard view (the published, shareable layout)
• One or more query tabs (underlying queries)
• A workbook model (per-dashboard model customizations)

Documents can be created with full query and visualization configurations via queryPresentations. Fine-tuning tile layout is best done in the Omni UI.

Document Management

Create Document (Name Only)

curl -L -X POST "$OMNI_BASE_URL/api/v1/documents" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "your-model-id",
    "name": "Q1 Revenue Report"
  }'

Returns the new document's identifier, workbookId, and dashboardId.

Create Document with Queries and Visualizations

Use queryPresentations to create a document pre-populated with query tabs and visualization configurations.

Doc gap: The create-document API docs mention queryPresentations but don't show the complete structure. This section documents the full format.

curl -L -X POST "$OMNI_BASE_URL/api/v1/documents" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "your-model-id",
    "name": "Q1 Revenue Report",
    "queryPresentations": [
      {
        "name": "Total Revenue",
        "topicName": "order_items",
        "prefersChart": true,
        "visType": "omni-kpi",
        "fields": ["order_items.total_revenue"],
        "query": {
          "table": "order_items",
          "fields": ["order_items.total_revenue"],
          "join_paths_from_topic_name": "order_items",
          "visConfig": { "chartType": "kpi" }
        },
        "config": {
          "alignment": "left",
          "verticalAlignment": "top",
          "markdownConfig": [
            {
              "id": "kpi-1",
              "type": "number",
              "config": {
                "field": {
                  "row": "_first",
                  "field": { "name": "order_items.total_revenue", "pivotMap": {} },
                  "label": { "value": "Total Revenue" }
                },
                "descriptionBefore": ""
              }
            }
          ]
        }
      },
      {
        "name": "Monthly Revenue Trend",
        "description": "Revenue by month for the current quarter",
        "topicName": "order_items",
        "prefersChart": true,
        "visType": "basic",
        "fields": ["order_items.created_at[month]", "order_items.total_revenue"],
        "query": {
          "table": "order_items",
          "fields": [
            "order_items.created_at[month]",
            "order_items.total_revenue"
          ],
          "sorts": [
            { "column_name": "order_items.created_at[month]", "sort_descending": false }
          ],
          "filters": { "order_items.created_at": "this quarter" },
          "limit": 100,
          "join_paths_from_topic_name": "order_items",
          "visConfig": { "chartType": "lineColor" }
        },
        "config": {
          "x": { "field": { "name": "order_items.created_at[month]" } },
          "mark": { "type": "line" },
          "color": {},
          "series": [{ "field": { "name": "order_items.total_revenue" }, "yAxis": "y" }],
          "tooltip": [
            { "field": { "name": "order_items.created_at[month]" } },
            { "field": { "name": "order_items.total_revenue" } }
          ],
          "version": 0,
          "behaviors": { "stackMultiMark": false },
          "configType": "cartesian",
          "_dependentAxis": "y"
        }
      },
      {
        "name": "Revenue by Status",
        "topicName": "order_items",
        "prefersChart": true,
        "visType": "basic",
        "chartType": "barGrouped",
        "fields": ["order_items.status", "order_items.total_revenue"],
        "query": {
          "table": "order_items",
          "fields": [
            "order_items.status",
            "order_items.total_revenue"
          ],
          "sorts": [
            { "column_name": "order_items.total_revenue", "sort_descending": true }
          ],
          "limit": 10,
          "join_paths_from_topic_name": "order_items",
          "visConfig": { "chartType": "barColor" }
        },
        "config": {
          "y": { "field": { "name": "order_items.status" } },
          "mark": { "type": "bar" },
          "color": { "_stack": "group" },
          "series": [{ "field": { "name": "order_items.total_revenue" }, "xAxis": "x" }],
          "tooltip": [
            { "field": { "name": "order_items.status" } },
            { "field": { "name": "order_items.total_revenue" } }
          ],
          "version": 0,
          "behaviors": { "stackMultiMark": false },
          "configType": "cartesian",
          "_dependentAxis": "x"
        }
      }
    ]
  }'

Key Parameters (not fully documented elsewhere)

queryPresentation Object Reference

Query Object Reference

The query object within each query presentation uses the same structure as the Query API:

Note: modelId is not needed inside the query object — it's inherited from the document's top-level modelId.

visConfig Object

visConfig belongs inside the query object — not at the queryPresentation level. When passed as a sibling of query, it is silently dropped by the API.

visConfig alone does not control chart rendering. It stores the chart type hint on the query, but the actual rendering is driven by prefersChart, visType, and config at the queryPresentation level.

chartType values:

config Object

The config object at the queryPresentation level defines the actual chart rendering. Its structure varies by chart type — see references/queryPresentations.md for complete config examples by chart type.

The most reliable way to get the correct config for a given chart type is to build the chart in the Omni UI and read it back via GET /api/v1/documents/{documentId}.

Discovering the Full queryPresentation Structure from Existing Dashboards

The most reliable way to learn config, visType, and field names is to read an existing dashboard document:

Step 1: Find a reference dashboard

curl -L "$OMNI_BASE_URL/api/v1/documents" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Step 2: Get its full document

curl -L "$OMNI_BASE_URL/api/v1/documents/{documentId}" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Returns the complete queryPresentations array including topicName, visConfig, config, and the full query object for each tile — use this as the source of truth when recreating or templating dashboards.

Tip: Build a reference dashboard in the Omni UI with the chart types and styling you want, then read it via GET /api/v1/documents/{documentId} to capture the exact queryPresentations structure to use as a template.

Caveats When Copying queryPresentations from Existing Dashboards

• Strip model_extension_id from each query object — these reference model extensions scoped to the source document and will cause "Chart unavailable" errors in new documents.
• Filter to the tiles you want — GET /api/v1/documents/{id} returns all queries including workbook-only tabs not shown on the dashboard. Only pass the queryPresentations you want as visible tiles.
• Queries without topicName are valid — SQL-mode and tab-selector queries won't have a topicName. Do not add one.

Caveats when using queryPresentations from an existing document

• Filter to the tiles you want: get-dashboard-document returns all queries including workbook-only tabs not shown on the dashboard. Pass only the queryPresentations you want as visible tiles — every entry you include will become a visible tile in the new document.
• Strip model_extension_id: Some queries contain a model_extension_id that references a model extension scoped to the source document. These IDs are not valid in a new document and will cause "Chart unavailable" errors. Remove model_extension_id from each query object before posting.
• Queries without a topic are expected: SQL-mode queries and tab-selector queries (visType: "spreadsheet-tab") will not have a topicName — this is correct, do not add one.

Rename Document

curl -L -X PATCH "$OMNI_BASE_URL/api/v1/documents/{documentId}" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Revenue Report (Updated)",
    "clearExistingDraft": true
  }'

Set clearExistingDraft: true if the document has an existing draft, otherwise the API returns 409 Conflict.

Delete Document

curl -L -X DELETE "$OMNI_BASE_URL/api/v1/documents/{documentId}" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Soft-deletes the document (moves to Trash).

Move Document

curl -L -X PUT "$OMNI_BASE_URL/api/v1/documents/{documentId}/move" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderPath": "/Marketing/Reports",
    "scope": "organization"
  }'

Use "folderPath": null to move to root. scope is optional — auto-computed from the destination folder.

Duplicate Document

curl -L -X POST "$OMNI_BASE_URL/api/v1/documents/{documentId}/duplicate" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Copy of Q1 Revenue Report",
    "folderPath": "/Marketing/Reports"
  }'

Only published documents can be duplicated. Draft documents return 404.

Updating a Dashboard's Model

Push custom dimensions and measures to a specific dashboard by writing to its workbook model. This is a two-step flow:

Step 1 — get the document to find its workbook_id:

curl -L "$OMNI_BASE_URL/api/v1/documents/{documentId}" \
  -H "Authorization: Bearer $OMNI_API_KEY"
# → response includes "workbook_id"

Step 2 — POST YAML to the workbook model:

curl -L -X POST "$OMNI_BASE_URL/api/unstable/models/{workbookId}/yaml" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "order_items.view",
    "yaml": "views:\n  order_items:\n    dimensions:\n      is_high_value:\n        sql: \"${sale_price} > 100\"\n        label: High Value Order\n    measures:\n      high_value_count:\n        sql: \"${order_items.id}\"\n        aggregate_type: count_distinct\n        label: High Value Orders"
  }'

fileName must be "model", "relationships", or end with .view or .topic. The yaml value is a YAML string (not a JSON object). Writing to a workbook model skips git sync entirely — authorization is still checked against the underlying shared model's permissions.

Dashboard Filters

Get Current Filters

curl -L "$OMNI_BASE_URL/api/v1/dashboards/{dashboardId}/filters" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Update Filters

Warning: PUT and PATCH on /dashboards/{id}/filters have been reported to return 405 or 500 in some configurations. If filter updates fail, include filters during document creation instead (see below).

The most reliable way to create dashboard filters is to include filterConfig and filterOrder in the initial POST /api/v1/documents call. See references/filterConfig.md for complete examples of each filter type.

curl -L -X POST "$OMNI_BASE_URL/api/v1/documents" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "your-model-id",
    "name": "Filtered Dashboard",
    "filterConfig": {
      "date_filter": {
        "type": "date",
        "label": "Date Range",
        "kind": "TIME_FOR_INTERVAL_DURATION",
        "ui_type": "PAST",
        "left_side": "6 months ago",
        "right_side": "6 months"
      },
      "state_filter": {
        "type": "string",
        "label": "State",
        "kind": "EQUALS",
        "fieldName": "users.state",
        "values": []
      }
    },
    "filterOrder": ["date_filter", "state_filter"],
    "queryPresentations": [...]
  }'

The keys in filterConfig (e.g., "date_filter") are arbitrary IDs — they must match the entries in filterOrder. To learn the exact filter structure, read filters from an existing dashboard with GET /api/v1/dashboards/{dashboardId}/filters.

Filter Types

Date Range — type: "date", kind: "TIME_FOR_INTERVAL_DURATION"

String Dropdown — type: "string", kind: "EQUALS", values: []

Boolean Toggle — type: "boolean", is_negative: false

Hidden Filter — any filter with "hidden": true (applied but not visible)

Date Granularity Picker — type: "FIELD_SELECTION", kind: "TIMEFRAME" with options array

URL Patterns

After creating or finding content, always provide the user a direct link:

Dashboard: {OMNI_BASE_URL}/dashboards/{identifier}
Workbook:  {OMNI_BASE_URL}/w/{identifier}

The identifier comes from the document's identifier field in API responses (not id, which is null for workbooks).

Recommended Build Workflows

API-First (Full Programmatic Creation)

Aim for minimal API calls. Batch everything into the document creation POST.

1. Discover fields — use omni-model-explorer to find topic + fields (1-2 calls)
2. Optionally read a reference dashboard — GET /api/v1/documents/{id} to capture queryPresentations patterns (1 call)
3. Create document — single POST /api/v1/documents with queryPresentations + filterConfig + filterOrder all in one call
4. Share the link — return {OMNI_BASE_URL}/dashboards/{identifier} to the user
5. Refine in UI — tile layout, chart styling, and advanced config are best done in the Omni UI

UI-First (Hybrid Approach)

1. Prepare the Model — use omni-model-builder for shared fields, or update-model for dashboard-specific fields
2. Build in UI — add tiles, choose viz types, arrange the grid, set filters
3. Iterate via API — update model fields, extract queries for reuse

Dashboard Downloads

# Start async download
curl -L -X POST "$OMNI_BASE_URL/api/v1/dashboards/{dashboardId}/download" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "pdf" }'

# Poll job
curl -L "$OMNI_BASE_URL/api/v1/jobs/{jobId}/status" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Docs Reference

• Documents API · Dashboard Filters · Dashboard Downloads · Query API · Schedules API · Visualization Types

Related Skills

• omni-model-explorer — understand available fields
• omni-model-builder — create shared model fields
• omni-query — test queries before adding to dashboards
• omni-content-explorer — find existing dashboards to learn from
• omni-embed — embed dashboards you've built in external apps