For AI agents: markdown of this page — /docs-content-en/entities/files/copyto.md documentation index — /llms.txt

Copy file

POST /v1/files/:id/copyto

Creates a copy of the file in the specified folder. The original stays in place; the copy gets a new identifier.

Parameters

Parameter In Type Required Description
id path number yes ID of the file to copy. Get it via GET /v1/files

Request fields (body)

Field Type Required Description
targetFolderId number yes Destination folder ID. Get it via GET /v1/folders

Examples

curl — personal key

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetFolderId": 649}' \
  https://vibecode.bitrix24.com/v1/files/9250/copyto

curl — OAuth app

Terminal 
curl -X POST \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetFolderId": 649}' \
  https://vibecode.bitrix24.com/v1/files/9250/copyto

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/files/9250/copyto',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ targetFolderId: 649 }),
  }
)
const body = await res.json()
if (!body.success) {
  console.error(body.error.code, body.error.message)
} else {
  console.log('Copy created, ID:', body.data.id)
}

JavaScript — OAuth app

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/files/9250/copyto',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ targetFolderId: 649 }),
  }
)
const body = await res.json()

Response fields

Returns the object of the created copy.

Field Type Description
success boolean true on a successful copy
data.id number ID of the created copy (differs from the original ID)
data.name string File name
data.code string | null System file code
data.storageId number Storage ID
data.type string Object type — always "file"
data.folderId number Destination folder ID
data.deletedType number Deletion type: 0 — not deleted
data.globalContentVersion number Global content version
data.fileId number Internal identifier of the file content
data.size number Size in bytes
data.createdBy number ID of the user who created the copy
data.updatedBy number ID of the user who updated the copy
data.deletedBy number | null ID of the user who deleted it. Always null for a new copy
data.createdAt string (ISO 8601) Copy creation date
data.updatedAt string (ISO 8601) Copy update date
data.deletedAt string | null Deletion date. Always null for a new copy
data.downloadUrl string Direct file download URL
data.detailUrl string URL of the file card in Bitrix24

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 9253,
    "name": "doc-copy-test.txt",
    "code": null,
    "storageId": 1,
    "type": "file",
    "folderId": 649,
    "deletedType": 0,
    "globalContentVersion": 1,
    "fileId": 34869,
    "size": 4,
    "createdBy": 1,
    "updatedBy": 1,
    "deletedBy": null,
    "createdAt": "2026-05-06T09:35:13.000Z",
    "updatedAt": "2026-05-06T09:35:13.000Z",
    "deletedAt": null,
    "downloadUrl": "https://...",
    "detailUrl": "https://..."
  }
}

Error response example

400 — targetFolderId not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "targetFolderId is required."
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS Required targetFolderId parameter not provided
400 INVALID_PARAMS targetFolderId is not a positive integer
400 INVALID_ID The id in the path is not a positive integer
400 OPERATION_FAILED Bitrix24 returned an empty result — the copy was not performed
401 TOKEN_MISSING No authorization tokens found for the portal
403 SCOPE_DENIED The API key lacks the disk scope
422 BITRIX_ERROR A file with the same name already exists in the destination folder

Full list of common API errors — Error codes.

Known specifics

  • The copy gets a new ID. The original stays in its source folder unchanged. The copy identifier (the data.id field) does not match the original identifier — use data.id for further work with the copy.
  • Copying works between storages. Unlike the move operation (POST /v1/files/:id/moveto), copying is allowed even when the source file and the destination folder belong to different storages.
  • Name conflict. If a file with the same name already exists in the destination folder, the operation fails with a 422 error. Rename the original or choose a different folder.

See also