Omni Dashboard filters API

openapi: 3.1.0
info:
  title: Omni AI Dashboard filters API
  description: "The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more.  \n"
  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: Dashboard filters
paths:
  /v1/dashboards/{dashboardId}/filters:
    get:
      tags:
      - Dashboard filters
      summary: Get dashboard filters and controls
      description: 'Returns the filter and control configuration for a dashboard, including IDs, types, current default values, and metadata.

        '
      security:
      - bearerAuth: []
      operationId: getDashboardFilters
      parameters:
      - name: dashboardId
        in: path
        required: true
        schema:
          type: string
        description: The dashboard identifier
      - name: userId
        in: query
        required: false
        schema:
          type: string
        description: '**Requires an Organization API key**. Optional user ID that attributes the action to the specified user.


          Personal Access Tokens (PATs) cannot use this parameter.

          '
      responses:
        '200':
          description: Dashboard filter and control configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardFiltersResponse'
              example:
                identifier: abc123
                filters:
                  order_status:
                    type: string
                    kind: EQUALS
                    values:
                    - completed
                    - pending
                    label: Order Status
                    description: Filter by order status
                    required: false
                    hidden: false
                  order_date:
                    type: date
                    kind: WITHIN_RANGE
                    left_side: '2024-01-01'
                    right_side: '2024-12-31'
                    label: Order Date
                controls:
                - id: field_selector
                  type: FIELD_SELECTION
                  kind: FIELD
                  label: Metric Selector
                  field: orders.revenue
                  options:
                  - label: Revenue
                    value: orders.revenue
                  - label: Quantity
                    value: orders.quantity
                filterOrder:
                - order_status
                - order_date
                - field_selector
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions to view the specified dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Dashboard not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    patch:
      tags:
      - Dashboard filters
      summary: Update dashboard filters/controls
      x-mint:
        content: "Updates filter and/or control values on a dashboard. Allows setting or resetting values for specific filters/controls by ID.\n\n<Note>\n  Updates to published dashboards go through a [draft/publish workflow](/content/develop). If a draft already exists for the dashboard, you must set `clearExistingDraft: true` to discard it and proceed with the update.\n</Note>\n"
      security:
      - bearerAuth: []
      operationId: updateDashboardFilters
      parameters:
      - name: dashboardId
        in: path
        required: true
        schema:
          type: string
        description: The dashboard identifier
      - name: userId
        in: query
        required: false
        schema:
          type: string
        description: '**Requires an Organization API key**. Membership ID to act on behalf of.


          Personal Access Tokens (PATs) cannot use this parameter.

          '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DashboardFiltersUpdateRequest'
            examples:
              updateFilterValues:
                summary: Update filter values
                value:
                  filters:
                    order_status:
                      values:
                      - shipped
                      - delivered
              updateWithClearDraft:
                summary: Update with existing draft (clear draft)
                value:
                  clearExistingDraft: true
                  filters:
                    order_status:
                      values:
                      - shipped
              updateControlLabel:
                summary: Update control label
                value:
                  controls:
                    field_selector:
                      label: Choose Metric
              updateDisplayOrder:
                summary: Update display order
                value:
                  filterOrder:
                  - order_date
                  - field_selector
                  - order_status
      responses:
        '200':
          description: Updated filter and control configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardFiltersResponse'
        '400':
          description: 'Bad Request. Possible error messages:


            - `Invalid filter IDs: <ids>. Available filter IDs: <ids>`

            - `Invalid control IDs: <ids>. Available control IDs: <ids>`

            - `Invalid IDs in filterOrder: <ids>. Available IDs: <ids>`

            - `Invalid filter update for <id>: <validation error>`

            - `Invalid control update for <id>: <validation error>`

            - `Request must include at least one filter, control, or filterOrder to update`

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions to edit the specified dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Dashboard not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          description: A draft already exists for this document. Set `clearExistingDraft` to `true` to discard and proceed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    DashboardControl:
      type: object
      description: 'Control configuration.

        '
      properties:
        id:
          type: string
          description: Control identifier
        type:
          type: string
          description: 'The control type:


            - `FIELD_SELECTION`: Single field selector dropdown

            - `MULTI_FIELD_SELECTION`: Parent control for grouping child controls

            - `FIELD_PICKER`: Multi-select field picker

            - `PERIOD_OVER_PERIOD`: Time comparison control

            '
          enum:
          - FIELD_SELECTION
          - MULTI_FIELD_SELECTION
          - FIELD_PICKER
          - PERIOD_OVER_PERIOD
        kind:
          type: string
          description: 'The control kind, ex: `FIELD`

            '
        label:
          type: string
          description: Display label
        fieldOrder:
          type: string
          enum:
          - query
          - control
          description: 'Controls how fields are ordered when selected from the control. When `control`, fields are added in the order they are selected from the control. When `query`, fields already in the query retain their position and the control only adds or removes fields. See the [Dashboard control documentation](/visualize-present/dashboards/controls#multi-field-reordering) for more information.

            '
        description:
          type: string
          description: Help text description
        hidden:
          type: boolean
          description: Whether the control is hidden
        field:
          type: string
          description: '**Applicable to `FIELD_SELECTION` controls.** The currently selected field.

            '
        options:
          type: array
          description: Available options for field selection
          items:
            type: object
            properties:
              label:
                type: string
                description: Option display label
              value:
                type: string
                description: Option value
    DashboardFiltersResponse:
      type: object
      properties:
        identifier:
          type: string
          description: The dashboard identifier
        filters:
          type: object
          description: Map of filter ID to filter configuration
          additionalProperties:
            $ref: '#/components/schemas/DashboardFilter'
        controls:
          type: array
          description: Array of control configurations
          items:
            $ref: '#/components/schemas/DashboardControl'
        filterOrder:
          type: array
          description: Ordered list of filter and control IDs for display
          items:
            type: string
    DashboardControlUpdate:
      type: object
      description: Partial update for a dashboard control
      properties:
        label:
          type: string
          description: Display label
        description:
          type: string
          description: Help text description
        hidden:
          type: boolean
          description: Whether to hide the control
    DashboardFilter:
      type: object
      description: 'Filter configuration.

        '
      properties:
        type:
          type: string
          description: 'The filter data type.


            - `string`: Text-based filters (equals, contains, etc.)

            - `number`: Numeric filters (equals, between, etc.)

            - `date`: Date range filters

            - `boolean`: True/false filters

            - `null`: Null check filters

            - `by_query`: Query-based dynamic filters

            - `user_attribute`: Filters based on user attributes

            - `composite`: Combined filters

            '
          enum:
          - string
          - number
          - date
          - boolean
          - 'null'
          - by_query
          - user_attribute
          - composite
        kind:
          type: string
          description: The filter operation kind (e.g., `EQUALS`, `WITHIN_RANGE`)
        values:
          type: array
          description: Default values for string/number filters
          items:
            type: string
        left_side:
          type: string
          description: Start value for date range filters
        right_side:
          type: string
          description: End value for date range filters
        label:
          type: string
          description: Display label
        description:
          type: string
          description: Help text description
        required:
          type: boolean
          description: Whether the filter is required
        hidden:
          type: boolean
          description: Whether the filter is hidden
    DashboardFilterUpdate:
      type: object
      description: Partial update for a dashboard filter
      properties:
        values:
          type: array
          description: New default values for string/number filters
          items:
            type: string
        left_side:
          type: string
          description: New start value for date filters
        right_side:
          type: string
          description: New end value for date filters
        label:
          type: string
          description: Display label
        description:
          type: string
          description: Help text description
        required:
          type: boolean
          description: Whether the filter is required
        hidden:
          type: boolean
          description: Whether to hide the filter
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
    DashboardFiltersUpdateRequest:
      type: object
      description: Request body for updating dashboard filters and controls. At least one of `filters`, `controls`, or `filterOrder` must be provided with at least one entry.
      properties:
        clearExistingDraft:
          type: boolean
          default: false
          description: When `true`, discards any existing draft before applying updates
        filters:
          type: object
          description: Map of filter ID to partial update
          additionalProperties:
            $ref: '#/components/schemas/DashboardFilterUpdate'
        controls:
          type: object
          description: Map of control ID to partial update
          additionalProperties:
            $ref: '#/components/schemas/DashboardControlUpdate'
        filterOrder:
          type: array
          description: New display order (filter and control IDs)
          items:
            type: string
  responses:
    MethodNotAllowed:
      description: Method Not Allowed - Invalid HTTP method for this endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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#token-types).


        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`

        '