Rename file

put
Rename file API
https://api.imagekit.io/v1/files/rename
You can programmatically rename an already existing file in the media library using rename file API.
Request
Response
Request
Headers
Authorization
required
string
base64 encoding of your_private_api_key: 
Note the colon in the end.
Body Parameters
filePath
required
string
The full path of the file you want to rename. For example - /path/to/file.jpg
newFileName
required
string
The new name of the file. A filename can contain:

- Alphanumeric Characters: a-z , A-Z , 0-9 (including Unicode letters, marks, and numerals in other languages). 
- Special Characters: . _ and -

Any other character, including space, will be replaced by _.

purgeCache
optional
boolean
Option to purge cache for the old file URL. 

When set to true, it will internally issue a purge cache request on CDN to remove cached content on the old URL. E.g. if an old file was accessible at  -https://ik.imagekit.io/demo/old-filename.jpg, a purge cache request will be issued to remove the CDN cache for this URL. This purge request is counted against your monthly purge quota.

Default value - false
Response
200: OK
On success, you will receive purgeRequestId in the response body, which can be used to get the purge request status. This is only sent if the purgeCache is set to true in the request. Otherwise, the response is an empty JSON.
// When purgeCache is set to true
{
    purgeRequestId: "598821f949c0a938d57563bd"
}
​
// When purgeCache is not set or set to false, response is empty
{}
207: Multi Status
In case purgeCache is set to true in the request and your total purge request count has exceeded the quota, we will rename the file but won't be able to purge the old URL from the CDN.
{
    "message" : "File renamed successfully but we could not purge the CDN cache for old URL because of rate limits on purge API.",
    "help" : "For support kindly contact us at [email protected] .",
    "reason" : "PURGE_FAILED" 
}
404: Not Found
If no file is found at the specified filePath in the media library, then a 404 response is returned.
{
     "message" : "No file found in media library at filePath /path/to/file.jpg",
     "help" : "For support kindly contact us at [email protected] .",
     "reason" : "FILE_MISSING" 
}
409: Conflict
If a file with newFileName already exist in the same location, a 409 response is returned.
{
     "message" : "File with name newFileName already exists at the same location.",
     "help" : "For support kindly contact us at [email protected] .",
     "reason" : "FILE_ALREADY_EXISTS" 
}
Response structure and status code
In case of an error, you will get an error code along with the error message. On success, you will receive a 200 status code with the JSON-encoded response body.
The response depends upon the value of purgeCache in the request. If purgeCache is set to true, the response contains purgeRequestId, which can be used to get the purge cache status.
purgeCache=true
purgeCache=false or unset
purgeCache=true
// When purgeCache is set to true, we send the purge request ID.
// You can use this to get purge status
{
    purgeRequestId: "598821f949c0a938d57563bd"
}
purgeCache=false or unset
// When purgeCache is set to false or not set
{}
Example
Here is an example request to understand API usage.
cURL
cURL
curl -X PUT "https://api.imagekit.io/v1/files/rename" \
-H 'Content-Type: application/json' \
-u your_private_key: -d '
{
	"filePath" : "/path/to/old-file-name.jpg",
	"newFileName" : "new-file-name.jpg",
	"purgeCache": false
}
'
Move file
Create folder
Last updated 2 months ago
Rename file

putRename file API

Response structure and status code

Example

put
Rename file API
