GET STARTED WITH APIs
Overview
ENDPOINTS
Upload File
Digital Asset Management (DAM)
Custom metadata fields
Managing assets
Get file details
get
Update file details
patch
Delete file
delete
Delete multiple files
post
Copy file
post
Move file
post
Rename file
put
List file versions
get
Get file version details
get
Delete file version
delete
Restore file version
put
Add tags (bulk)
post
Remove tags (bulk)
post
Remove AI tags (bulk)
post
List and search assets
get
Managing folders
Caching
File Metadata
Account Management API
put
https://api.imagekit.io
/v1/files/rename

You can rename an already existing file in the media library using rename file API. This operation would rename all file versions of the file.

Note: The old URLs will stop working. The file/file version URLs cached on CDN will continue to work unless a purge is requested.

Request

Body

filePath
string
required

The full path of the file you want to rename.

Example:
/path/to/file.jpg
newFileName
string
required

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 _.

Example:
newFileName.jpg
purgeCache
boolean

Option to purge cache for the old file and its versions' URLs.

When set to true, it will internally issue a purge cache request on CDN to remove cached content of old file and its versions. This purge request is counted against your monthly purge quota.

Note: If the old file were accessible at https://ik.imagekit.io/demo/old-filename.jpg, a purge cache request would be issued against https://ik.imagekit.io/demo/old-filename.jpg* (with a wildcard at the end). It will remove the file and its versions' URLs and any transformations made using query parameters on this file or its versions. However, the cache for file transformations made using path parameters will persist. You can purge them using the purge API. For more details, refer to the purge API documentation.

Default value - false

Example:
true
Auth
API key
:
Body
Note

Here, you can explore machine-generated code examples. For practical applications, refer to the examples section below, which includes detailed code snippets from the ImageKit SDKs.

curl --request PUT \
  --url https://api.imagekit.io/v1/files/rename \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic 123' \
  --header 'Content-Type: application/json' \
  --data '{
  "filePath": "/path/to/file.jpg",
  "newFileName": "newFileName.jpg",
  "purgeCache": true
}'

Responses

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.

Body

purgeRequestId
string

Unique identifier of the purge request. This can be used to check the status of the purge request.

1
{
2
  "purgeRequestId": "string"
3
}

Examples

Here are some examples to understand the API usage.

Copy
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
}
'

var ImageKit = require("imagekit");

var imagekit = new ImageKit({
  publicKey: "your_public_api_key",
  privateKey: "your_private_api_key",
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/",
});

imagekit.renameFile(
  {
    filePath: "/path/to/old-file-name.jpg",
    newFileName: "new-file-name.jpg",
    purgeCache: false, // optional
  },
  function (error, result) {
    if (error) console.log(error);
    else console.log(result);
  }
);

from imagekitio import ImageKit

imagekit = ImageKit(
    public_key='your_public_api_key',
    private_key='your_private_api_key',
    url_endpoint = 'https://ik.imagekit.io/your_imagekit_id/'
)

rename_file = imagekit.rename_file(options=RenameFileRequestOptions(file_path="/file_path.jpg",
                                                                    new_file_name="new_file_name.jpg",
                                                                    purge_cache=True))

print("Rename file-", rename_file, end="\n\n")

# Raw Response
print(rename_file.response_metadata.raw)

# print the purge request id
print(rename_file.purge_request_id)

use ImageKit\ImageKit;

$public_key = "your_public_api_key";
$your_private_key = "your_private_api_key";
$url_end_point = "https://ik.imagekit.io/your_imagekit_id";

$imageKit = new ImageKit(
    $public_key,
    $your_private_key,
    $url_end_point
);

$filePath='/path/to/old-file-name.jpg';
$newFileName = 'new-file-name.jpg';
$renameFile = $imageKit->rename([
    'filePath' => $filePath,
    'newFileName' => $newFileName,
    'purgeCache' => false,  // optional
]);

echo("Rename File : " . json_encode($renameFile));

RenameFileRequest renameFileRequest = new RenameFileRequest();
renameFileRequest.setFilePath("/path/to/old-file-name.jpg");
renameFileRequest.setNewFileName("new-file-name.jpg");
renameFileRequest.setPurgeCache(false);
ResultRenameFile resultRenameFile = ImageKit.getInstance().renameFile(renameFileRequest);

imagekitio = ImageKitIo::Client.new("your_private_key", "your_public_key", "your_url_endpoint")
imagekitio.rename_file(
  file_path: '/path/to/old-file-name.jpg',
  new_file_name: 'new-file-name.jpg',
  purge_cache: false #optional
)

resp, err := ik.Media.RenameFile(ctx, media.RenameFileParam{
    FilePath: "/path/to/old-file-name.jpg",
    NewFileName: "new-file-name.jpg",
    PurgeCache: false, // Optional
})

var imagekit = new ImageKit({
    publicKey : "your_public_api_key",
    privateKey : "your_private_api_key",
    urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});

RenameFileRequest renameFileRequest = new RenameFileRequest
    {
        filePath = "path_1",
        newFileName = "file_name",
        purgeCache = false
    };
ResultRenameFile resultRenameFile = imagekit.RenameFile(renameFileRequest);