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

# Refresh model schema

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

## Path parameters

- `modelId` string, uuid, required — Model UUID

## Query parameters

- `branch_id` string, uuid — Branch ID for branch-based schema refresh. Required when branch-based schema refresh is enabled for the connection. Must not be provided when branch-based schema refresh is not enabled.
- `hard_refresh` 'true' | 'false' — When true (the default), performs a hard refresh that fully discards and rebuilds the schema model. When false, performs a soft refresh that merges newly generated views with the existing model. Must be set to false when `schemas` or `tables` filters are provided.
- `schemas` string — Optional comma-separated list of schemas to refresh selectively. Only the listed schemas are reloaded; the rest of the schema model is preserved. Requires `hard_refresh=false`.
- `tables` string — Optional comma-separated list of tables to refresh selectively. Only the listed tables are reloaded; the rest of the schema model is preserved. Requires `hard_refresh=false`.

## Response `200`

Refresh job started

- ModelsRefreshResponse
  - `jobId` string, required — Job ID for the refresh operation
  - `modelId` string, required — Model ID being refreshed
  - `status` 'running' | 'completed' | 'failed', required — Current status of the refresh

## Other responses

- `400` — Bad request - branch_id required when branch-based schema refresh is enabled, branch_id not allowed when it is not enabled, or hard refresh requested with selective schemas/tables filters
- `401` — Authentication required
- `403` — Permission denied - a branch refresh requires permission to update the branch; a direct refresh requires connection admin, or modeler on a connection with exactly one shared model
- `404` — Model not found

---

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