Files and folders REST API reference

Article
01/19/2015

Learn about the REST API for File, FileVersion, Folder, and related resources.

Applies to: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

In this article
About the request examples in this article
Explore the SharePoint 2013 files and folders REST syntax
File resource
FileCollection resource
FileVersion resource
FileVersionCollection resource
Folder resource
FolderCollection resource
Additional resources

About the request examples in this article

The request examples in this article assume that you’re using the cross-domain library (SP.RequestExecutor.js) to make cross-domain requests, so they use SP.AppContextSite in the endpoint URI. See How to: Access SharePoint 2013 data from apps using the cross-domain library for more information.

Before you use a request example, do the following:

Change <app web url>, <host web url>, and other placeholder data such as any IDs, names, or paths of SharePoint entities.
If you’re not using the cross-domain library, include an X-RequestDigest header to send the form digest value in all POST requests and a content-length header for POST requests that send data in the request body.
If you're not making cross-domain requests, remove SP.AppContextSite(@target) and ?@target='<host web url>' from the endpoint URI.
If you’re using OAuth, include an Authorization header ("Authorization": "Bearer " + <access token>) to send the OAuth access token.
Remove the line breaks from the url and body property values in the request examples. Line breaks are added to the examples to make them easier to read.
If you want the server to return responses in Atom format, remove the "accept": "application/json; odata=verbose" header.

See Additional resources for links to more information about using the cross-domain library, OAuth, and the SharePoint REST service. See How REST requests differ by environment and Properties used in REST requests for information about request formats.

Tip

The SharePoint Online REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. For details and links to code samples, see Make batch requests with the REST APIs. This option is not yet supported for on-premise SharePoint.

Explore the SharePoint 2013 files and folders REST syntax

Visually explore the SharePoint 2013 lists and list items REST syntax.

Explore other SharePoint REST syntax diagrams:

Lists and list items | Users and groups

Download the combined PDF of all the SharePoint REST syntax diagrams.

File resource

Represents a file in a SharePoint Web site that can be a Web Part Page, an item in a document library, or a file in a folder.

Endpoint URI | Properties | Methods | OData representation

Endpoint URI

http://<site url>/_api/web/getfilebyserverrelativeurl('/<folder name>/<file name>')

Supported HTTP methods

GET | PUT (media resource)

GET | DELETE | POST (File resource)

Request examples

GET request example: Get file contents (media resource)

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/$value
    ?@target='<host web url>'",
  method: "GET",
  binaryStringResponseBody: true,
  success: successHandler,
  error: errorHandler
});

GET request example: Get file metadata

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

PUT request example: Update file contents (media resource)

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.txt')/$value
    ?@target='<host web url>'",
  method: "POST",
  body: "Updated contents of the file go here",
  headers: { "X-HTTP-Method":"PUT" },
  success: successHandler,
  error: errorHandler
});

Check out the file first to prevent other users from changing it. Then, check it back in after you've made your changes. See the CheckOut method and the CheckIn method.

DELETE request example: Delete a file

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method":"DELETE" },
  success: successHandler,
  error: errorHandler
});

Or you can use the Recycle method to remove the file and get the GUID of the recycled item.

Note

See the Add method for an example that shows how to create a file and add it to a folder.

File properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
Author	SP.User	R	No	Gets a value that specifies the user who added the file.
CheckedOutByUser	SP.User	R	No	Gets a value that returns the user who has checked out the file.
CheckInComment	String	R	Yes	Gets a value that returns the comment used when a document is checked in to a document library.
CheckOutType	Int32	R	Yes	Gets a value that indicates how the file is checked out of a document library. Represents an SP.CheckOutType value: Online = 0; Offline = 1; None = 2. The checkout state of a file is independent of its locked state.
ContentTag	String	R	Yes	Returns internal version of content, used to validate document equality for read purposes.
CustomizedPageStatus	Int32	R	Yes	Gets a value that specifies the customization status of the file. Represents an SP.CustomizedPageStatus value: None = 0; Uncustomized = 1; Customized = 2.
ETag	String	R	Yes	Gets a value that specifies the ETag value.
Exists	Boolean	R	Yes	Gets a value that specifies whether the file exists.
Length	Int64	R	Yes	Gets the size of the file in bytes, excluding the size of any Web Parts that are used in the file.
Level	Byte	R	Yes	Gets a value that specifies the publishing level of the file. Represents an SP.FileLevel value: Published = 1; Draft = 2; Checkout = 255.
ListItemAllFields	SP.ListItem	R	No	Gets a value that specifies the list item field values for the list item corresponding to the file.
LockedByUser	SP.User	R	No	Gets a value that returns the user that owns the current lock on the file.
MajorVersion	Int32	R	Yes	Gets a value that specifies the major version of the file.
MinorVersion	Int32	R	Yes	Gets a value that specifies the minor version of the file.
ModifiedBy	SP.User	R	No	Gets a value that returns the user who last modified the file.
Name	String	R	Yes	Gets the name of the file including the extension.
ServerRelativeUrl	String	R	Yes	Gets the relative URL of the file based on the URL for the server.
TimeCreated	DateTime	R	Yes	Gets a value that specifies when the file was created.
TimeLastModified	DateTime	R	Yes	Gets a value that specifies when the file was last modified.
Title	String	R	Yes	Gets a value that specifies the display name of the file.
UiVersion	Int32	R	Yes	Gets a value that specifies the implementation-specific version identifier of the file.
UiVersionLabel	String	R	Yes	Gets a value that specifies the implementation-specific version identifier of the file.
Versions	SP.FileVersionCollection	R	No	Gets a value that returns a collection of file version objects that represent the versions of the file.

File methods

Approve
CancelUpload
CheckIn
CheckOut
ContinueUpload
CopyTo
DeleteObject
Deny
FinishUpload
GetLimitedWebPartManager
MoveTo
OpenBinaryStream
Publish
Recycle
SaveBinaryStream
StartUpload
UndoCheckOut
Unpublish

Approve

Approves the file submitted for content approval with the specified comment.

Only documents in lists that are enabled for content approval can be approved.

Endpoint	/approve(comment)
Parameters	comment Type: String The comment for the approval.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /approve(comment='Check-in comment for the approval.')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

CancelUpload method

Stops the chunk upload session without saving the uploaded data. If the file doesn’t already exist in the library, the partially uploaded file will be deleted. Use this in response to user action (as in a request to cancel an upload) or an error or exception.

Use the uploadId value that was passed to the StartUpload method that started the upload session.

This method is currently available only on Office 365.

Endpoint	/cancelupload(uploadId)
Parameters	uploadID Type: GUID The unique identifier of the upload session.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /cancelupload(uploadId=guid'GUID')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

CheckIn method

Checks the file in to a document library based on the check-in type.

Endpoint	/checkin(comment, checkInType)
Parameters	comment Type: String A comment for the check-in. Its length must be <= 1023. checkInType Type: Int32 The SP.CheckinType for the file: MinorCheckIn = 0; MajorCheckIn = 1; OverwriteCheckIn = 2.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /checkin(comment='Check-in comment.',checkintype=0)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

CheckOut method

Checks out the file from a document library based on the check-out type.

Endpoint	/checkout
Parameters	None
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /checkout
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

ContinueUpload method

Continues the chunk upload session with an additional fragment. The current file content is not changed.

Use the uploadId value that was passed to the StartUpload method that started the upload session.

This method is currently available only on Office 365.

Endpoint	/continueupload(uploadId, fileOffset)
Parameters	uploadID Type: GUID The unique identifier of the upload session. fileOffset Type: Int64 The size of the offset into the file where the fragment starts. Send the file contents (stream) in the post body.
HTTP method	POST
Response	Type: Int64 The size of the total uploaded data in bytes.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /continueupload(uploadId=guid'GUID',fileOffset=8388608)
    ?@target='<host web url>'",
  method: "POST",
  body: stream containing intermediate chunk of file
  success: successHandler,
  error: errorHandler
});

CopyTo method

Copies the file to the destination URL.

Endpoint	/copyto(strNewUrl, bOverWrite)
Parameters	strNewUrl Type: String The absolute URL or server relative URL of the destination file path to copy to. bOverWrite Type: Boolean true to overwrite a file with the same name in the same location; otherwise false.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /copyto(strnewurl='/foldername/filename.docx',boverwrite=false)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

DeleteObject method

The recommended way to delete a file is to send a DELETE request to the File resource endpoint, as shown in File request examples.

Deny method

Denies approval for a file that was submitted for content approval.

Only documents in lists that are enabled for content approval can be denied.

Endpoint	/deny(comment)
Parameters	comment Type: String The comment for the denial.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /deny(comment='Check-in comment for the denial.')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

FinishUpload method

Uploads the last file fragment and commits the file. The current file content is changed when this method completes.

Use the uploadId value that was passed to the StartUpload method that started the upload session.

This method is currently available only on Office 365.

Endpoint	/finishupload(uploadId, fileOffset)
Parameters	uploadID Type: GUID The unique identifier of the upload session. fileOffset Type: Int64 The size of the offset into the file where the fragment starts. Send the file contents (stream) in the post body.
HTTP method	POST
Response	Type: SP.File The newly uploaded file.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /finishupload(uploadId=guid'GUID',fileOffset=125829120)
    ?@target='<host web url>'",
  method: "POST",
  body: stream containing final chunk of file
  success: successHandler,
  error: errorHandler
});

GetLimitedWebPartManager method

Specifies the control set used to access, modify, or add Web Parts associated with this Web Part Page and view.

An exception is thrown if the file is not an ASPX page.

Endpoint	/getlimitedwebpartmanager(scope)
Parameters	scope Type: Int32 The SP.WebParts.PersonalizationScope view on the Web Parts page. User = 0; Shared = 1.
HTTP method	GET
Response	Type: SP.WebParts.LimitedWebPartManager The associated control set used to access, modify, or add Web Parts.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/fileName.aspx')
    /getlimitedwebpartmanager(scope=0)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MoveTo method

Moves the file to the specified destination URL.

Endpoint	/moveto(newUrl, flags)
Parameters	newUrl Type: String The absolute URL or server relative URL of the destination file path to move to. flags Type: Int32 The bitwise SP.MoveOperations value for how to move the file. Overwrite = 1; AllowBrokenThickets (move even if supporting files are separated from the file) = 8.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /moveto(newurl='/Other Folder/filename.docx',flags=1)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OpenBinaryStream method

Opens the file as a stream.

Endpoint	/openbinarystream
Parameters	None
HTTP method	GET
Response	Type: Stream The specified file stream.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /openbinarystream
    ?@target='<host web url>'",
  method: "GET",
  binaryStringResponseBody: true,
  success: successHandler,
  error: errorHandler
});

Note

Or you can use $value from the file resource to open a file. Example: …/getfilebyserverrelativeurl('/Shared Documents/filename.docx')/$value.

Publish method

Submits the file for content approval with the specified comment.

Endpoint	/publish(comment)
Parameters	comment Type: String The comment for the published file. Its length must be <= 1023.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /publish(comment='Check-in comment for the publish operation.')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

Recycle method

Moves the file to the Recycle Bin and returns the identifier of the new Recycle Bin item.

Endpoint	/recycle
Parameters	None
HTTP method	POST
Response	Type: GUID The GUID of the recycled file.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /recycle
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

SaveBinaryStream method

Endpoint	/savebinary
Parameters	Send the file contents (stream) in the post body.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /savebinarystream
    ?@target='<host web url>'",
  method: "POST",
  body: "This is the new content.",
  success: successHandler,
  error: errorHandler
});

StartUpload method

Starts a new chunk upload session and uploads the first fragment. The current file content is not changed when this method completes. The method is idempotent (and therefore does not change the result) as long as you use the same values for uploadId and stream. The upload session ends either when you use the CancelUpload method or when you successfully complete the upload session by passing the rest of the file contents through the ContinueUpload and FinishUpload methods.

For example, you can pass a 35 MB file by dividing it into three 10 MB streams and one 5 MB stream and uploading them this way (using the resulting offset values of 10, 20 and 30 MB):

startUpload(GUID, stream1)
continueUpload(GUID, 10 MB, stream2)
continueUpload(GUID, 20 MB, stream3)
finishUpload(GUID, 30 MB, stream4)

The StartUpload and ContinueUpload methods return the size of the running total of uploaded data in bytes, so you can pass those return values to subsequent uses of ContinueUpload and FinishUpload.

This method is currently available only on Office 365.

Endpoint	/startupload(uploadId)
Parameters	uploadID Type: GUID The unique identifier of the upload session. Send the file contents (stream) in the post body.
HTTP method	POST
Response	Type: Int64 The size of the uploaded data in bytes.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /startupload(uploadId=guid'GUID')
    ?@target='<host web url>'",
  method: "POST",
  body: stream containing first chunk of file
  success: successHandler,
  error: errorHandler
});

UndoCheckOut method

Reverts an existing checkout for the file.

Endpoint	/undocheckout
Parameters	None
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /undocheckout
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

Unpublish method

Removes the file from content approval or unpublish a major version.

Endpoint	/unpublish
Parameters	comment Type: String The comment for the unpublish operation. Its length must be <= 1023.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /unpublish(comment='Check-in comment for the unpublish operation.')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a File resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared Documents/folderName/fileName.docx')",
        "uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')",
        "type":"SP.File"
      },
      "Author":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/Author"}},
      "CheckedOutByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/CheckedOutByUser"}},
      "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/ListItemAllFields"}},
      "LockedByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/LockedByUser"}},
      "ModifiedBy":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/ModifiedBy"}},
      "Versions":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName.docx')/Versions"}},
      "CheckInComment":"Revisions to the file.",
      "CheckOutType":2,
      "ContentTag":"{2FBB0C3C-4059-41A2-A5CF-3E076EA0A94C},2,3",
      "CustomizedPageStatus":0,
      "ETag":"\"{2FBB0C3C-4059-41A2-A5CF-3E076EA0A94C},2\"",
      "Exists":true,
      "Length":"20609",
      "Level":1,
      "MajorVersion":1,
      "MinorVersion":0,
      "Name":"fileName.docx",
      "ServerRelativeUrl":"/Shared Documents/folderName/fileName.docx",
      "TimeCreated":"2013-05-16T21:01:23Z",
      "TimeLastModified":"2013-05-18T04:57:32Z",
      "Title":"",
      "UIVersion":512,
      "UIVersionLabel":"1.0"
    }}

FileCollection resource

Represents a collection of File resources.

Endpoint URI | Methods | OData representation

Endpoint URI

http://<site url>/_api/web/getfolderbyserverrelativeurl('/<folder name>')/files

Supported HTTP methods

GET | POST

Request examples

GET request example: Get the metadata of all the files in a folder

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/files
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get file contents (media resource) by file name

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/files('filename.docx')/$value
    ?@target='<host web url>'",
  method: "GET",
  binaryStringResponseBody: true,
  success: successHandler,
  error: errorHandler
});

GET request example: Get file metadata

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/files('filename.docx')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
};

See File request examples for examples of how to retrieve a file by using the GetFileByServerRelativeUrl endpoint and how to update and delete a file. To create a file, see the Add method.

FileCollection methods

Add
AddTemplateFile
GetByUrl

Add method

Endpoint	/add(content, overwrite, url)
Parameters	content Type: Stream The contents of the file. Pass the content parameter in the request body. The maximum size of a binary file that you can add by using the REST API is 2 GB. overwrite Type: Boolean true to overwrite the file if it already exists; otherwise false. url Type: String The folder-relative URL of the file.
HTTP method	POST
Response	Type: SP.File The new file.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/files
    /add(overwrite=true,url='filename.txt')
    ?@target='<host web url>'",
  method: "POST",
  body: "Contents of the file go here",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

The following example shows how to upload a binary file by using the cross-domain library, which requires converting the file stream to a string. For a jQuery example, see How to: Upload a file by using the REST API and jQuery.

function addFile(arrayBuffer) { 
    var executor = new SP.RequestExecutor(appWebUrl);

    // Construct the endpoint.
    // The GetList method is available for SharePoint Online only. 
    var fileCollectionEndpoint = String.format(
         "{0}/_api/sp.appcontextsite(@target)/web/getlist('{1}')/" +
         "rootfolder/files/add(overwrite=true, url='{2}')?@target='{3}'",
         appWebUrl, listName, fileName, hostWebUrl);

    var fileData = '';
    var byteArray = new Uint8Array(arrayBuffer);
    for (var i = 0; i < byteArray.byteLength; i++) {
        fileData += String.fromCharCode(byteArray[i]);
    }

    // Send the request.
    executor.executeAsync({
        url: fileCollectionEndpoint,
        method: "POST",
        body: fileData,
        binaryStringRequestBody: true,
        headers: {"accept":"application/json;odata=verbose"},
        success: function (data) {
            alert('File upload succeeded.');
        },
        error: function (err) {
            alert('Error: ' + err.responseText);
        }
    });
}

AddTemplateFile method

Adds a ghosted file to an existing list or document library.

Endpoint	/addTemplateFile(urlOfFile,templateFileType)
Parameters	urlOfFile Type: String The server-relative URL where you want to save the file. templateFileType Type: Int32 The SP.TemplateFileType to use to create the file: StandardPage = 0; WikiPage = 1; FormPage = 2.
HTTP method	POST
Response	Type: SP.File The template file that was added.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents')/files
    /addtemplatefile(urloffile='/Shared Documents/newwikipage.aspx',templatefiletype=1)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByUrl method

Get the file at the specified URL.

The GetFileByServerRelativeUrl endpoint is recommended way to get a file. See SP.File request examples.

Endpoint	/getbyurl('<name or server-relative url of file>')
Parameters	None
HTTP method	GET
Response	Type: SP.File The file at the specified URL.

Request examples

Get file contents (media resource)

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/foldername')/files
    /getbyurl('filename.docx')/$value
    ?@target='<host web url>'",
  method: "GET",
  binaryStringResponseBody: true,
  success: successHandler,
  error: errorHandler
});

Get a file's metadata (File resource)

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/foldername')/files
    /getbyurl('filename.docx')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

See File request examples and FileCollection request examples to see other ways to get a file.

OData representation

The following example represents a FileCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared Documents/folderName/fileName1.docx')",
          "uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')",
          "type":"SP.File"
        },
        "Author":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/Author"}},
        "CheckedOutByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/CheckedOutByUser"}},
        "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/ListItemAllFields"}},
        "LockedByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/LockedByUser"}},
        "ModifiedBy":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/ModifiedBy"}},
        "Versions":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName1.docx')/Versions"}},
        "CheckInComment":"",
        "CheckOutType":2,
        "ContentTag":"{2FBB0C3C-4059-41A2-A5CF-3E076EA0A94C},4,7",
        "CustomizedPageStatus":0,
        "ETag":"\"{2FBB0C3C-4059-41A2-A5CF-3E076EA0A94C},4\"",
        "Exists":true,
        "Length":"20609",
        "Level":1,
        "MajorVersion":1,
        "MinorVersion":0,
        "Name":"fileName1.docx",
        "ServerRelativeUrl":"/Shared Documents/folderName/fileName1.docx",
        "TimeCreated":"2013-05-16T21:01:23Z",
        "TimeLastModified":"2013-06-09T02:38:14Z",
        "Title":"Title of fileName1",
        "UIVersion":512,
        "UIVersionLabel":"1.0"
        },{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared Documents/folderName/fileName2.docx')",
          "uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')",
          "type":"SP.File"
        },
        "Author":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/Author"}},
        "CheckedOutByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/CheckedOutByUser"}},
        "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/ListItemAllFields"}},
        "LockedByUser":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/LockedByUser"}},
        "ModifiedBy":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/ModifiedBy"}},
        "Versions":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFileByServerRelativeUrl('/Shared%20Documents/folderName/fileName2.docx')/Versions"}},
        "CheckInComment":"",
        "CheckOutType":2,
        "ContentTag":"{E654B970-C4BF-4DC5-9719-B5B01CAD6FD9},4,9",
        "CustomizedPageStatus":0,
        "ETag":"\"{E654B970-C4BF-4DC5-9719-B5B01CAD6FD9},4\"",
        "Exists":true,
        "Length":"12263",
        "Level":1,
        "MajorVersion":1,
        "MinorVersion":0,
        "Name":"fileName2.docx",
        "ServerRelativeUrl":"/Shared Documents/folderName/fileName2.docx",
        "TimeCreated":"2013-05-18T05:01:51Z",
        "TimeLastModified":"2013-06-09T02:38:59Z",
        "Title":"Title of fileName2",
        "UIVersion":512,
        "UIVersionLabel":"1.0"
      }]}}

FileVersion resource

Represents a version of an File resource.

Endpoint URI | Properties | Methods | OData representation

Endpoint URI

http://<site url>/_api/web/getfilebyserverrelativeurl('/<folder name>/<file name>')/versions(<version id>)

Supported HTTP methods

GET | POST | DELETE

Request examples

GET request example: Get the metadata for a file version

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions(512)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a specific version of a file

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions(513)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method":"DELETE" },
  success: successHandler,
  error: errorHandler
});

FileVersion properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')
    /versions(512)/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
CheckInComment	String	R	Yes	Gets a value that specifies the check-in comment.
Created	DateTime	R	Yes	Gets a value that specifies the creation date and time for the file version.
CreatedBy	SP.User	R	No	Gets a value that specifies the user that represents the creator of the file version.
ID	Int32	R	Yes	Gets the internal identifier for the file version.
IsCurrentVersion	Boolean	R	Yes	Gets a value that specifies whether the file version is the current version.
Size	Int32	R	Yes
Url	String	R	Yes	Gets a value that specifies the relative URL of the file version based on the URL for the site or subsite.
VersionLabel	String	R	Yes	Gets a value that specifies the implementation specific identifier of the file. Uses the majorVersionNumber.minorVersionNumber format, for example: 1.2.

FileVersion methods

DeleteObject

DeleteObject method

The recommended way to delete a file version is to send a DELETE request to the FileVersion resource endpoint, as shown in FileVersion request examples.

OData representation

The following example represents a FileVersion resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/web/getfilebyserverrelativeurl('/Shared Documents/folderName/fileName1.docx')/versions(512)",
        "uri":"http://<site url>/_api/web/getfilebyserverrelativeurl('/Shared%20Documents/folderName/fileName1.docx')/versions(512)",
        "type":"SP.FileVersion"
      },
      "CreatedBy":{"__deferred":{"uri":"http://<site url>/_api/web/getfilebyserverrelativeurl('/Shared%20Documents/folderName/fileName1.docx')/versions(512)/CreatedBy"}},
      "CheckInComment":"Revisions to the file.",
      "Created":"2013-06-10T04:02:53Z",
      "ID":512,
      "IsCurrentVersion":true,
      "Size":20609,
      "Url":"_vti_history/512/Shared Documents/folderName/fileName1.docx",
      "VersionLabel":"1.0"
    }}

FileVersionCollection resource

Represents a collection of FileVersion resources.

Endpoint URI | Methods | OData representation

Endpoint URI

http://<site url>/_api/web/getfilebyserverrelativeurl('/<folder name>/<file name>')/versions

HTTP methods

This resource supports the following HTTP methods:

GET | POST

Request example

GET request example: Get the metadata for all versions of a file

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get the metadata for a file version

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions(512)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

FileVersionCollection methods

DeleteAll
DeleteById
DeleteByLabel
GetById
RestoreByLabel

DeleteAll method

Deletes all the file version objects in the collection.

Endpoint	/deleteall
Parameters	None
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /deleteall
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

DeleteById method

Deletes the specified version of the file.

Endpoint	/deletebyid(vid)
Parameters	vid Type: Int32 The ID of the file version to delete.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /deletebyid(vid=3)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

DeleteByLabel method

Deletes the file version object with the specified version label.

Endpoint	/deletebylabel(versionlabel)
Parameters	versionlabel Type: String The SP.FileVersion.VersionLabel property of the file version to delete.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /deletebylabel(versionlabel='1.2')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

GetById method

Endpoint	/getbyid(versionid)
Parameters	versionid Type: Int32 The ID of the file version to get.
HTTP method	GET
Response	Type: SP.FileVersion The specified file version.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /getbyid(512)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can pass the version ID directly to the collection (…/versions(512)). See FileVersionCollection request examples.

RestoreByLabel method

Creates a new file version from the file specified by the version label.

Endpoint	/restorebylabel(versionlabel)
Parameters	versionlabel Type: String The SP.FileVersion.VersionLabel property of the file version to restore.
HTTP method	POST
Response	None

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfilebyserverrelativeurl('/Shared Documents/filename.docx')/versions
    /restorebylabel(versionlabel='1.2')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a FileVersionCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/SP.FileVersiona6a6bb00-2b96-41e6-a901-46df015183b9",
          "uri":"http://<site url>/_api/SP.FileVersiona6a6bb00-2b96-41e6-a901-46df015183b9",
          "type":"SP.FileVersion"
        },
        "CreatedBy":{"__deferred":{"uri":"http://<site url>/_api/SP.FileVersiona6a6bb00-2b96-41e6-a901-46df015183b9/CreatedBy"}},
        "CheckInComment":"",
        "Created":"2013-06-10T04:02:53Z",
        "ID":512,
        "IsCurrentVersion":true,
        "Size":20609,
        "Url":"_vti_history/512/Shared Documents/folderName/fileName1.docx",
        "VersionLabel":"1.0"
        },{
        "__metadata":{
          "id":"http://<site url>/_api/SP.FileVersion6accd876-7579-47b6-9779-19a24f6ab8a1",
          "uri":"http://<site url>/_api/SP.FileVersion6accd876-7579-47b6-9779-19a24f6ab8a1",
          "type":"SP.FileVersion"
        },
        "CreatedBy":{"__deferred":{"uri":"http://<site url>/_api/SP.FileVersion6accd876-7579-47b6-9779-19a24f6ab8a1/CreatedBy"}},
        "CheckInComment":"Revisions to the file.",
        "Created":"2013-06-11T17:42:41Z",
        "ID":513,
        "IsCurrentVersion":false,
        "Size":17973,
        "Url":"_vti_history/513/Shared Documents/folderName/fileName1.docx",
        "VersionLabel":"1.1"
      }]}}

Folder resource

Represents a folder on a SharePoint Web site.

Endpoint URI | Properties | Methods | OData representation

Endpoint URI

http://<site url>/_api/web/getfolderbyserverrelativeurl('/<folder name>')

Supported HTTP methods

GET | POST | DELETE | MERGE | PUT

Request examples

GET request example: Get a folder

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE request example: Change a folder

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Folder' }, 'WelcomePage':'Folder B/WelcomePage.aspx' }",
  headers: {
    "content-type": "application/json; odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a folder

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method":"DELETE" },
  success: successHandler,
  error: errorHandler
});

See FolderCollection request examples for an example of how to create a folder.

Folder properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

To set a writeable property, get the resource, set the property value in the body, and then use the MERGE method on the resource to merge your changes or use the PUT method to replace the resource. See Folder request examples for an example.

Property	Type	R/W	Returned with resource	Description
ContentTypeOrder	Collection(SP.ContentTypeId)	R	Yes	Specifies the sequence in which content types are displayed.
Files	SP.FileCollection	R	No	Gets the collection of all files contained in the list folder. You can add a file to a folder by using the Add method on the folder’s FileCollection resource.
Folders	SP.FolderCollection	R	No	Gets the collection of list folders contained in the list folder.
ItemCount	Int32	R	Yes	Gets a value that specifies the count of items in the list folder.
ListItemAllFields	SP.ListItem	R	No	Specifies the list item field (2) values for the list item corresponding to the file.
Name	String	R	Yes	Gets the name of the folder.
ParentFolder	SP.Folder	R	No	Gets the parent list folder of the folder.
Properties	SP.PropertyValues	R	No	Gets the collection of all files contained in the folder.
ServerRelativeUrl	String	R	Yes	Gets the server-relative URL of the list folder.
UniqueContentTypeOrder	Collection(SP.ContentTypeId)	RW	Yes	Gets or sets a value that specifies the content type order.
WelcomePage	String	RW	Yes	Gets or sets a value that specifies folder-relative URL for the list folder welcome page.

Folder methods

DeleteObject
Recycle

DeleteObject method

The recommended way to delete a folder is to send a DELETE request to the Folder resource endpoint, as shown in Folder request examples.

Recycle method

Moves the list folder to the Recycle Bin and returns the identifier of the new Recycle Bin item.

Endpoint	/recycle
HTTP method	POST
Parameters	None
Response	Type: GUID The ID of the recycle operation.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')
    /recycle
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a Folder resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared Documents/Folder A')",
        "uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')",
        "type":"SP.Folder"
      },
      "Files":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/Files"}},
      "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/ListItemAllFields"}},
      "ParentFolder":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/ParentFolder"}},
      "Properties":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/Properties"}},
      "Folders":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Folder%20A')/Folders"}},
      "ItemCount":7,
      "Name":"Folder A",
      "ServerRelativeUrl":"/Shared Documents/Folder A",
      "WelcomePage":""
    }}

FolderCollection resource

Represents a collection of Folder resources.

Endpoint URI | Methods | OData representation

Endpoint URI

http://<site url>/_api/web/folders (top-level folders at the root site)
http://<site url>/_api/web/getfolderbyserverrelativeurl('/<folder name>')/folders

Supported HTTP methods

GET | POST

Request examples

GET request example: Get the folders at the root site

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/folders
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get the folders in a document library

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents')/folders
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a folder by name

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/folders('Folder B')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST request example: Create a folder (or you can use the Add method)

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /getfolderbyserverrelativeurl('/Shared Documents/Folder A')/folders
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata':{ 'type': 'SP.Folder' }, 'ServerRelativeUrl':'Folder B' }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

See Folder request examples for examples of how to update and delete a folder.

FolderCollection methods

Add
GetByUrl

Add method

Adds the folder that is located at the specified URL to the collection.

Endpoint	/add(url)
Parameters	url Type: String The path where you want to add the folder (including the name of the new folder) as a fully-qualified URL, server-relative URL, or site-relative URL.
HTTP method	POST
Response	Type: SP.Folder The newly added folder.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/folders
    /add('/Shared Documents/Folder A/Folder B')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetByUrl method

Endpoint	/getbyurl('<server-relative folder url>')
Parameters	Type: String The server-relative URL of the folder.
HTTP method	GET
Response	Type: SP.Folder The specified folder.

Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/folders
    /getbyurl('Folder B')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

You can also pass a folder name directly to a folder collection. Example: …/folders('Folder B'). See FolderCollection request examples.

OData representation

The following example represents a FolderCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared Documents/Forms')",
          "uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')",
          "type":"SP.Folder"
        },
        "Files":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/Files"}},
        "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/ListItemAllFields"}},
        "ParentFolder":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/ParentFolder"}},
        "Properties":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/Properties"}},
        "Folders":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/Forms')/Folders"}},
        "ItemCount":0,
        "Name":"Forms",
        "ServerRelativeUrl":"/Shared Documents/Forms",
        "WelcomePage":""
        },{
        "__metadata":{
          "id":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared Documents/folderName')",
          "uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')",
          "type":"SP.Folder"
        },
        "Files":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/Files"}},
        "ListItemAllFields":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/ListItemAllFields"}},
        "ParentFolder":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/ParentFolder"}},
        "Properties":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/Properties"}},
        "Folders":{"__deferred":{"uri":"http://<site url>/_api/Web/GetFolderByServerRelativeUrl('/Shared%20Documents/folderName')/Folders"}},
        "ItemCount":4,
        "Name":"folderName",
        "ServerRelativeUrl":"/Shared Documents/folderName",
        "WelcomePage":""
      }]}}

Share via

Files and folders REST API reference

About the request examples in this article

Explore the SharePoint 2013 files and folders REST syntax

File resource

Endpoint URI

Supported HTTP methods

Request examples

File properties

File methods

Approve

CancelUpload method

CheckIn method

CheckOut method

ContinueUpload method

CopyTo method

DeleteObject method

Deny method

FinishUpload method

GetLimitedWebPartManager method

MoveTo method

OpenBinaryStream method

Publish method

Recycle method

SaveBinaryStream method

StartUpload method

UndoCheckOut method

Unpublish method

OData representation

FileCollection resource

Endpoint URI

Supported HTTP methods

Request examples

FileCollection methods

Add method

AddTemplateFile method

GetByUrl method

OData representation

FileVersion resource

Endpoint URI

Supported HTTP methods

Request examples

FileVersion properties

FileVersion methods

DeleteObject method

OData representation

FileVersionCollection resource

Endpoint URI

HTTP methods

Request example

FileVersionCollection methods

DeleteAll method

DeleteById method

DeleteByLabel method

GetById method

RestoreByLabel method

OData representation

Folder resource

Endpoint URI

Supported HTTP methods

Request examples

Folder properties

Folder methods

DeleteObject method

Recycle method

OData representation

FolderCollection resource

Endpoint URI

Supported HTTP methods

Request examples

FolderCollection methods

Add method

GetByUrl method

OData representation

Additional resources

Additional resources