---
title: "Move or rename files"
method: POST
path: "/v2/projects/{projectId}/files/move"
tags: ["Files"]
---

# Move or rename files

`POST /v2/projects/{projectId}/files/move`

## Request

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

Move or rename 1–25 files on a branch. 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', required

## Request body

- object
  - `branchId` string: Branch ID. Defaults to the project default branch.
  - `moves` object[], required: 1–25 moves; each old and each new file ID may appear once, and no file ID may be both an old and a new file ID.
    - `oldFileId` string, required
    - `newFileId` string, required
    - `newFileName` string, required

## Response `200`

Result for each move, in request order, even when every move fails; a failed move has `status: "failed"` and an `error`. Each move clones the latest source file and its translations under the new file ID and makes the new file ID current in place of the old one.

- object
  - `summary` BatchWriteSummary, required: Number of `results` in total and by `status`.
    - `total` integer, required
    - `succeeded` integer, required
    - `failed` integer, required
  - `results` object[], required: One result per move, in request order.
    - `oldFileId` string, required
    - `newFileId` string, required
    - `newSourceFileId` string
    - `clonedTranslationsCount` integer
    - `status` 'succeeded' | 'failed', required
    - `error` string: Why the item failed.
    - `code` 'invalid_request' | 'unauthenticated' | 'payment_required' | 'permission_denied' | 'not_found' | 'conflict' | 'route_retired' | 'payload_too_large' | 'unsupported_media_type' | 'locked' | 'not_ready' | 'rate_limited' | 'internal_error' | 'upstream_error' | 'unavailable' | 'already_exists' | 'api_key_invalid' | 'api_version_too_old' | 'api_version_unsupported' | 'branch_not_found' | 'cdn_not_enabled' | 'content_empty' | 'credits_insufficient' | 'cursor_invalid' | 'default_branch_conflict' | 'drive_access_insufficient' | 'drive_account_not_connected' | 'file_too_large' | 'google_account_not_linked' | 'integration_managed_file' | 'integration_not_connected' | 'invalid_content_encoding' | 'ip_not_allowed' | 'layout_not_supported' | 'locale_not_allowed' | 'org_integration_required' | 'permission_missing' | 'permission_not_grantable' | 'plan_feature_unavailable' | 'project_limit_reached' | 'response_too_large' | 'source_file_not_found' | 'spend_limit_reached' | 'sync_required' | 'target_inaccessible' | 'target_locales_missing' | 'translation_not_ready' | 'unsupported_content_encoding' | 'upload_incomplete' | 'usage_limit_reached': Machine-readable cause of the failure. Present when `error` is.

## Other responses

- `400`: The request is malformed or failed validation, including a file ID that is both an `oldFileId` and a `newFileId`, as in a swap, cycle or chain; move through an unused file ID in separate requests instead. Nothing is changed.
- `401`: Authentication is missing or invalid.
- `403`: The caller is authenticated but not allowed to perform this operation or access the requested resource.
- `404`: The requested resource was not found.
- `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`: 9 warning
  - added the new `integration_managed_file` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `400`
  - added the new `integration_managed_file` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `401`
  - added the new `integration_managed_file` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `403`
  - added the new `integration_managed_file` enum value to the `allOf[#/components/schemas/ErrorResponse]/code` response property for the response status `404`
  - …5 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/generaltranslation/apis/general-translation-api/changes/v2/projects/:projectId/files/move/post.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)
