---
title: "Update files"
method: PATCH
path: "/v2/projects/{projectId}/files"
tags: ["Files"]
---

# Update files

`PATCH /v2/projects/{projectId}/files`

## Request

- Base URL: `https://api.gtx.dev`
- URL: `https://api.gtx.dev/v2/projects/{projectId}/files`
- Auth: HTTP bearer

Update 1–100 source files or translations in one atomic batch. Requires `project:files:write`.

## Path parameters

- `projectId` string, required

## Headers

- `gt-api-version` '2025-01-01.v0' | '2025-11-03.v1' | '2026-02-18.v1' | '2026-03-06.v1' | '2026-10-08.v1'

## Request body

- object: An absent field keeps its stored value. `null` clears a nullable field or removes a map entry; other fields reject `null`. In batches and imports, items match stored items by natural key, stored items absent from the batch are untouched, and nothing else is deleted. A blank CSV cell counts as absent.
  - `files` object[], required: 1–100 source files or translations; each branch, file, version and locale may appear once.
    - `fileId` string, required
    - `branchId` string: Branch ID. Defaults to the project default branch.
    - `versionId` string, required: Source version ID.
    - `locale` string: Translation locale. Omit to update the source file.
    - `metadata` object, required
      - `previewUrl` string, uri, nullable: Page that shows this version of the file.

## Response `200`

Each file after the update, in request order. Repeating a request is safe.

- object
  - `files` object[], required: Each file after the update, in request order.
    - `branchId` string, required
    - `fileId` string, required
    - `versionId` string, required
    - `locale` string: Translation locale as stored. Absent for a source file.
    - `metadata` object, required
      - `previewUrl` string, uri, nullable: Page that shows this version of the file.

## Other responses

- `400`: The request is malformed or failed validation.
- `401`: Authentication is missing or invalid.
- `403`: The caller is authenticated but not allowed to perform this operation or access the requested resource.
- `404`: A translation does not exist. Nothing is written.
- `409`: A source file version belongs to an integration, which owns its metadata. Nothing is written.
- `413`: The request, or the data it would return, exceeds a size or item limit.
- `415`: The request body's Content-Type is missing or not supported, or its Content-Encoding is not supported. Send the body as application/json, uncompressed or gzip-encoded.
- `429`: Too many requests. The rate limit was exceeded.
- `500`: An unexpected server error occurred.

## Changes

- **2026-11-06** `39f0059275f1`: 20 warning
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `400`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `401`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `403`
  - added the new `invalid_content_encoding` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `404`
  - …16 more
- **2026-11-05** `d8e2891005f3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/generaltranslation/apis/general-translation-api/changes/v2/projects/:projectId/files/patch.md)

---

[API](https://skmtc.dev/generaltranslation/apis/general-translation-api.md) - [All operations](https://skmtc.dev/generaltranslation/apis/general-translation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/generaltranslation/apis/general-translation-api/revisions/1ebafb7f823e?raw)
