---
title: "Create or update YAML files"
method: POST
path: "/v1/models/{modelId}/yaml"
tags: ["Models"]
---

# Create or update YAML files

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

Create or overwrite a YAML file for a model. The file can be a special file (`model` or `relationships`) or a YAML file ending in `.topic` or `.view`.

The following models cannot be edited using this endpoint:

- Schema models
- Models using git follower mode

## Path parameters

- `modelId` string, uuid, required

## Request body

- object
  - `branchId` string, uuid — **Required if git pull requests are required for the model.** The ID of the branch to create or update. To retrieve branch IDs, use the [List models](/api/models/list-models) endpoint with `modelKind=BRANCH`.
  - `fileName` string, required — The name of the YAML file. Valid values are: - `model` - [Model file](/modeling/models) - `relationships` - [Relationships file](/modeling/relationships) - `<topic_name>.topic` - [Topic file](/modeling/topics/parameters) - `<view_name>.view` - [View file](/modeling/views)
  - `yaml` string, required — The YAML contents of the file. This can be empty, in which case: - If empty and used with `mode: extension` the file will be removed from the model - If empty and used with `mode: combined`, the file will be ignored in the model
  - `mode` 'combined' | 'extension' | 'staged' | 'merged' | 'history', required — The mode to use when creating or overwriting the YAML file. **Note**: Workbook models must use `combined` mode if there is a `branchId`.
  - `commitMessage` string — **Required for [git-enabled models](/integrations/git).** Commit message describing the change.
  - `previousChecksum` string — Checksum of the file when fetched, for conflict detection. Obtain this value from the [Get model YAML endpoint](/api/models/get-model-yaml) by including the `includeChecksums` parameter. If the file has been modified since you fetched it, the request will fail with a `File has been modified since it was fetched` error.
  - `fullyResolved` boolean — If `true`, accepts fully-resolved YAML. This means that Omni will resolve any extension (`extends`) usage and place the changes into the appropriate model files. When `false` (default), the YAML is saved as-is to the specified file. This means that even if extensions are used, they will not be included in the changes.

## Response `200`

YAML file updated successfully

- object
  - `fileName` string — The name of the file that was created or updated.
  - `success` boolean — Indicates the request was successful.

## Other responses

- `400` — Bad Request Possible error messages: - `<parameter>: <parameter> is required` - `modelId: Invalid uuid` - `branchId: Invalid uuid` - `<parameter>: Invalid value <description>` - `File has been modified since it was fetched`
- `403` — Forbidden Possible error messages: - `Permission denied` - `Feature not enabled`
- `404` — Not Found Possible error messages: - `Model with id <modelId> does not exist` - `Branch does not exist`
- `405` — Method Not Allowed - Invalid HTTP method for this endpoint
- `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)