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

# Refresh schema

> <Note>
  This endpoint requires either **Connection Admin** or **Modeler** permissions:

  - **Modelers** can use this endpoint on connections that have exactly **one** shared model
  - **Connection Admins** can use this endpoint on any connection they are an admin of, whether the connection has one or multiple models
</Note>

Refreshes the schema of the specified model. This will cause the model to reflect the latest changes to schemas, views, and fields from the data source. Schema refreshes will remove structures that are no longer present in the source, but not anything created by users.

Depending on whether the **Branch-based schema refresh** setting is configured:

- If **Branch-based schema refresh** is enabled, the `branch_id` query parameter is required. The `branch_id` is validated against the shared model.
- If **Branch-based schema refresh** isn't enabled, do not provide the `branch_id` parameter. The API will return a `400` error in this case.




## OpenAPI

````yaml /api/openapi.yaml post /v1/models/{modelId}/refresh
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/models/{modelId}/refresh:
    post:
      tags:
        - Models
      summary: Refresh schema
      description: >
        <Note>
          This endpoint requires either **Connection Admin** or **Modeler** permissions:

          - **Modelers** can use this endpoint on connections that have exactly **one** shared model
          - **Connection Admins** can use this endpoint on any connection they are an admin of, whether the connection has one or multiple models
        </Note>


        Refreshes the schema of the specified model. This will cause the model
        to reflect the latest changes to schemas, views, and fields from the
        data source. Schema refreshes will remove structures that are no longer
        present in the source, but not anything created by users.


        Depending on whether the **Branch-based schema refresh** setting is
        configured:


        - If **Branch-based schema refresh** is enabled, the `branch_id` query
        parameter is required. The `branch_id` is validated against the shared
        model.

        - If **Branch-based schema refresh** isn't enabled, do not provide the
        `branch_id` parameter. The API will return a `400` error in this case.
      operationId: refreshSchema
      parameters:
        - name: modelId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The ID of the model to be refreshed.
        - name: branch_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: >
            **Required if Branch-based schema refresh is enabled**. The ID of
            the branch for models with this setting enabled.


            Do not provide this parameter when the setting is not enabled.
        - name: hard_refresh
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: >
            Whether to perform a hard refresh (removes dropped objects) or soft
            refresh (additive only). Defaults to true (hard refresh).
        - name: schemas
          in: query
          required: false
          schema:
            type: string
          description: >
            Comma-separated list of schemas to selectively refresh. Can only be
            used when `hard_refresh=false`.
        - name: tables
          in: query
          required: false
          schema:
            type: string
          description: >
            Comma-separated list of tables to selectively refresh. Can only be
            used when `hard_refresh=false`.
      responses:
        '200':
          description: Model refresh started
          content:
            application/json:
              schema:
                type: object
                properties:
                  modelId:
                    type: string
                    format: uuid
                    description: ID of the model.
                  status:
                    type: string
                    example: running
                    description: >-
                      Status of the schema refresh. This value will be `running`
                      to indicate that the refresh has started.
        '400':
          description: >
            Bad Request


            Possible error messages:


            - `Bad Request: modelId: Invalid uuid`

            - `Bad Request: branch_id: Invalid uuid`

            - `Bad Request: branch_id is required when branch schema refresh is
            enabled`

            - `Bad Request: branch_id must not be provided when branch schema
            refresh is not enabled`

            - `Bad Request: selective schemas/tables filters require
            hard_refresh=false`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: |
            Not Found

            Possible causes:

            - Model not found
            - Branch not found or does not belong to the model's shared model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - bearerAuth: []
components:
  schemas:
    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>
  responses:
    Forbidden:
      description: Forbidden - Insufficient permissions
      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`

````