---
title: "Refresh schema"
method: POST
path: "/v1/models/{modelId}/refresh"
tags: ["Models"]
---

# Refresh schema

`POST /v1/models/{modelId}/refresh`

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

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

## Path parameters

- `modelId` string, uuid, required

## Query parameters

- `branch_id` string, uuid
- `hard_refresh` boolean
- `schemas` string
- `tables` string

## Response `200`

Model refresh started

- object
  - `jobId` string, uuid — ID of the job.
  - `modelId` string, uuid — ID of the model.
  - `status` string — Status of the schema refresh. This value will be `running` to indicate that the refresh has started.

## Other responses

- `400` — 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`
- `401` — Missing or invalid authentication
- `403` — Forbidden - Insufficient permissions
- `404` — Not Found Possible causes: - Model not found - Branch not found or does not belong to the model's shared model
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)