I have a question on how to change an existing file on SharePoint document library using REST API. I have a couple of files in the location http://site url/<RootFolder>/<SubFolder>/File.docx. I have a UI where it lists all the files from this subfloder location. When the user clicks on edit i am enabling the file name as textbox where the user can change the name of the file.

After doing some research i found that Constructing an endpoint that looks like this: https://<site url>/_api/web/lists/getbytitle('Documents')/items(<item id>) we can edit the file metadata properties. But i could not able to figure out the best way to update the filename of existing document that resides on SharePoint Doc library.

Could someone please help me with the REST API query to fetch the file and the approach to update the filename?

2 Answers 2


You could consider at least two options to rename a file.

Option 1. Rename file name

You could update the name of the existing list item as demonstrated below


function rename(webUrl,listTitle,itemId,fileName){
   var endpointUrl = webUrl + "/_api/web/lists/getbytitle('" + listTitle + "')/items(" + itemId +  ")";
   return executeJson(endpointUrl)
      var itemPayload = {};
      itemPayload['__metadata'] = {'type': data.d['__metadata']['type']};
      itemPayload['Title'] = fileName;
      itemPayload['FileLeafRef'] = fileName;
      var itemUrl = data.d['__metadata']['uri'];
      var headers = {};
      headers["X-HTTP-Method"] = "MERGE";
      headers["If-Match"] =  "*";
      return executeJson(itemUrl,"POST",headers,itemPayload);

var webUrl = _spPageContextInfo.webAbsoluteUrl; // web url
var listTitle = "Documents";  //list title
var itemId = 1;  //list item id
var fileName = "SP User Guide.docx"; //new file name


Option 2. Use MoveTo REST endpoint

File could be renamed via MoveTo REST endpoint endpoint:



function moveTo(webUrl,sourceFileUrl,targetFileUrl){
   var endpointUrl = webUrl + "/_api/web/getfilebyserverrelativeurl('" + sourceFileUrl + "')/moveto(newurl='" + targetFileUrl + "',flags=1)";
   return executeJson(endpointUrl,"POST");

var webUrl = _spPageContextInfo.webAbsoluteUrl; // web url
var sourceFileUrl = "/Documents/SP2010.docx";
var targetFileUrl = "/Documents/SP2013.docx";


executeJson function:

function executeJson(url,method,headers,payload) 
    headers = headers || {};
    method = method || 'GET';
    headers["Accept"] = "application/json;odata=verbose";
    if(method == "POST") {
        headers["X-RequestDigest"] = $("#__REQUESTDIGEST").val();

    var ajaxOptions = 
       url: url,   
       type: method,  
       contentType: "application/json;odata=verbose",
       headers: headers
    if(method == "POST") {
      ajaxOptions.data = JSON.stringify(payload);
    return $.ajax(ajaxOptions);
  • { "error": { "code": "-2130575257, Microsoft.SharePoint.SPException", "message": { "lang": "en-US", "value": "The specified name is already in use.\n\nThe document or folder name was not changed. To change the name to a different value, close this dialog and edit the properties of the document or folder." } } } Using Option 1, I get this error. Can I use option 2 to rename a file to a name already taken by another file in the same directory structure? More like what the UI does (when it merges the 2 files) when you try to upload a file with existing name. Dec 2, 2016 at 12:45

So a couple of things you are going to need to do here is to make sure you get the form digest before you can update the list. To find this information take a look at Wictor Wilen's blog. In the section under "How to refresh Token" you can see how to get the form digest.

Once you have that, you need to update the list item. It's pretty straight forward. I haven't used the rest API before to do this, and I don't have my dev environment handy to test, but this should work. When you access a list item, you also have have access to the fields, including the name field which you should be able to change the filename with. The following code should work, but you may need to modify it to meet your needs:

   url: "http://<siteurl>/_api/web/lists/GetByTitle('ListTitle')/items('itemID'),
type: "POST",
   dataType: "json",
   Body: { '__metadata': { 'type': 'SP.Data.<ListName>ListItem' }, 'Name': 'NewName.docx'}
   headers: { 
          "Accept": "application/json;odata=verbose",
          "X-RequestDigest" : $("#__REQUESTDIGEST").val(),
          "X-HTTP-Method": "MERGE",
           "If-Match": "*"
 Success: DoSuccess,
 Error: DoError,

Hope this helps.

  • 2
    I almost downvoted this answer for It's pretty straight forward followed by a revelation of how you have not attempted it before and a bunch of shoulds. As anything SharePoint, nothing seems to be straightforward and there's a whole bunch of shoulds and not enough wills
    – BotNet
    Nov 7, 2016 at 15:04

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.