> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Update dashboard filters/controls



## OpenAPI

````yaml /api/openapi.yaml patch /v1/dashboards/{dashboardId}/filters
openapi: 3.1.0
info:
  title: Omni API
  description: >
    The Omni REST API provides programmatic access to your Omni instance for
    managing users, documents, queries, schedules, and more.  
  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: AI
    description: AI-powered query generation
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Content
    description: Unified content retrieval (documents and folders)
  - name: Content migration
    description: Export and import dashboards
  - name: Content validator
    description: Validate content against models and perform find/replace operations
  - name: Dashboard downloads
    description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
  - name: Dashboard filters and controls
    description: Read and update dashboard filter and control default values
  - name: dbt
    description: Manage dbt configuration for connections
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: Document favorites
    description: Favorite and unfavorite documents
  - name: Document labels
    description: Apply and manage labels on documents
  - name: Document permissions
    description: Manage document-level access
  - name: Labels
    description: >
      Manage labels in an organization. Labels can be applied to documents and
      folders to help organize and categorize content.


      **Label types:**

      - **Basic labels**: Can be created and managed by any user

      - **Verified labels**: Indicate curated or officially sanctioned content.
      Admin-only.

      - **Homepage labels**: Appear on the organization homepage. Admin-only.
  - name: Folders
    description: Create and organize content folders
  - name: Folder permissions
    description: Manage folder-level access
  - name: Jobs
    description: Check status of asynchronous jobs
  - name: Models
    description: Create and manage data models
  - name: Model branches
    description: Manage model branches and merge changes
  - name: Model git configuration
    description: Manage git configuration for shared models
  - name: Queries
    description: Execute workbook queries
  - name: Schedules
    description: Create and manage scheduled tasks
  - name: Schedule recipients
    description: Manage schedule recipients
  - name: Schema refresh schedules
    description: Manage automated schema refresh schedules for connections
  - name: Topics
    description: Retrieve topic information from models
  - name: Uploads
    description: Manage file uploads
  - name: Users
    description: Manage users
  - name: User attributes
    description: Manage user attribute definitions
  - name: User groups
    description: Manage user groups
  - name: User model roles
    description: Manage model and connection role assignments for users
  - name: User group model roles
    description: Manage model and connection role assignments for user groups
  - name: Uploads
    description: Manage CSV and spreadsheet uploads
paths:
  /v1/dashboards/{dashboardId}/filters:
    patch:
      tags:
        - Dashboard filters
      summary: Update dashboard filters/controls
      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'
      security:
        - bearerAuth: []
components:
  schemas:
    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
    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
    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>
    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
    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
    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
        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
  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#personal-access-tokens-pat).


        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`

````