Rename or move a file
Changes a file's name or folder.
Permission
The key must be granted files.writedocs.documents.write
A key without it gets 403 insufficient_scope, with the missing permission named in details.
Renaming and filing are separate operations in the backend, so a request doing both makes two calls: the rename first, because it is idempotent and a retry after a half-done request lands in the same place.
Path parameters
| Field | Type | Description |
|---|---|---|
id required |
string | The file to change. |
Request body
Send a name, a folder_id, or both.
| Field | Type | Description |
|---|---|---|
name |
string | Renames the file. |
folder_id |
string | Moves it. An explicit empty string moves it to the root. |
Request
curl https://api.veruapis.com/v1/files/:id \
-X PATCH \
-H "Authorization: Bearer vak_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "name": "q3-report-final.pdf", "folder_id": "0192f002-0000-7a41-b8d2-5e9f0c3a7b41" }'Idempotency-Key is required on every write. Retrying with the same key returns the original response rather than repeating the operation, so a timeout is something you retry rather than something you investigate.
Response
| Field | Type | Description |
|---|---|---|
id |
string | |
type |
string |
file
|
title |
string | The display name. |
filename |
string | The name it was uploaded under. |
mime_type |
string | Sniffed from the bytes when it was stored, not taken from what the uploader declared. |
size_bytes |
integer | |
state |
string |
activetrashed
|
owner_id |
string | |
folder_id |
string | Empty for a file in the root. |
created_at |
RFC 3339 | |
updated_at |
RFC 3339 |
{
"data": {
"id": "0192a1c2-6f3e-7a41-b8d2-5e9f0c3a7b41",
"type": "file",
"title": "q3-report-final.pdf",
"filename": "q3-report.pdf",
"folder_id": "0192f002-0000-7a41-b8d2-5e9f0c3a7b41",
"updated_at": "2026-09-10T08:05:00Z"
},
"meta": { "request_id": "req_01j8z9...", "timestamp": "2026-09-02T10:00:00Z" }
}filename is what it was uploaded as and does not change; the display name does. An explicit empty folder_id moves it to the root.
Every failure uses the same shape, with a stable string code you can branch on. See the error reference.
Related
- DELETE Abort an upload
- POST Complete an upload
- POST Create a folder
- POST Start an upload
- DELETE Delete a file
- DELETE Delete a folder
- GET Download a file
- GET Get file metadata
- GET Get upload status
- GET List files
- GET List folders
- GET List file permissions
- POST Share a file
- DELETE Revoke file access
- PATCH Rename or move a folder
- PUT Upload a part