---
title: "Apply skill file changes"
method: POST
path: "/skills/{skill_id}/files/batch"
tags: ["Skill Files"]
---

# Apply skill file changes

`POST /skills/{skill_id}/files/batch`

## Request

- Base URL: `https://api.metorial.com`
- URL: `https://api.metorial.com/skills/{skill_id}/files/batch`
- Auth: HTTP bearer

Applies up to 100 put, delete and move changes one after another, in order. Every change is validated before any is applied, but changes are not applied atomically: if a change fails while being applied, the changes before it stay applied. Every change can carry its own if_match precondition.

## Path parameters

- `skill_id` string, required

## Headers

- `Metorial-Version` string

## Request body

- BodyRequest73
  - `changes` union[], required: The changes to apply, in order.
    - union
      - object
        - `type` 'put', required
        - `path` string, required: Path of the file inside the skill. A leading "/" is optional. Paths may contain letters, numbers, spaces and the characters . _ - ( ) $.
        - `content` string: The new text content of the file. Markdown files are stored as documents, other files as plain text files.
        - `file_id` string: The ID of a previously uploaded file to place at the path. Use this for binary files. Files that belong to a document cannot be attached; use content to write markdown documents.
        - `if_match` string, nullable: Only apply the change if the file still has this etag. Pass null to require that no file exists at the path yet. Omit to skip the check.
      - object
        - `type` 'delete', required
        - `path` string, required: Path of the file inside the skill. A leading "/" is optional. Paths may contain letters, numbers, spaces and the characters . _ - ( ) $.
        - `if_match` string: Only apply the change if the file still has this etag. Omit to skip the check.
      - object
        - `type` 'move', required
        - `path` string, required: Path of the file inside the skill. A leading "/" is optional. Paths may contain letters, numbers, spaces and the characters . _ - ( ) $.
        - `to_path` string, required: The new path of the file.
        - `if_match` string: Only apply the change if the file still has this etag. Omit to skip the check.

## Response `200`

Successful response

- SkillFileChangeList
  - `items` SkillFileChange[], required
    - `object` 'skill.file_change', required: String representing the object's type
    - `type` 'put' | 'delete' | 'move', required: The kind of change that was applied.
    - `path` string, required: The resulting path of the file. For moves, this is the new path.
    - `previous_path` string, nullable, required: The path the file was moved from. Only set for moves.
    - `file` object, nullable, required
      - `object` 'skill.file', required: String representing the object's type
      - `path` string, required: Path of the file inside the skill, always starting with "/".
      - `kind` 'document' | 'file', required: Markdown written with `content` is stored as a collaboratively editable document; everything else, including attached files, is stored as a file.
      - `size` number, required: Size of the file content in bytes.
      - `etag` string, required: Opaque version identifier of the file content. Pass it as `if_match` when writing to avoid overwriting changes made by others. The check is best-effort: a live collaborative edit landing between the check and the write is not detected. Listings do not flush pending live edits, so a listed etag can lag behind the one returned when fetching the file.
      - `skill_id` string, required: The ID of the skill the file belongs to.
      - `store_item_id` string, required: The ID of the store item backing this file.
      - `document_id` string, nullable, required: The ID of the backing document, for files of kind `document`.
      - `file_id` string, nullable, required: The ID of the backing file, for files of kind `file`.
      - `updated_at` string, date-time, required: When the file was last changed.
  - `pagination` object, required
    - `has_more_before` boolean, required
    - `has_more_after` boolean, required

## Other responses

- `400`: Invalid parameters or action
- `401`: Missing or invalid API key
- `403`: The key lacks permission for this resource
- `404`: No such resource
- `422`: Validation failed
- `429`: Rate limit exceeded
- `500`: Unexpected server error

---

[API](https://skmtc.dev/metorial/apis/metorial-api.md) - [All operations](https://skmtc.dev/metorial/apis/metorial-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metorial/apis/metorial-api/revisions/10ccc89f3eac?raw)