Get a special folder by name

Article
09/29/2021

Use the special collection to access a special folder by name.

Special folders provide simple aliases to access well-known folders in OneDrive without the need to look up the folder by path (which would require localization), or reference the folder with an ID. If a special folder is renamed or moved to another location within the drive, this syntax will continue to find that folder.

Special folders are automatically created the first time an application attempts to write to one, if it doesn't already exist. If a user deletes one, it is recreated when written to again.

Note: If you have read-only permissions and request a special folder that doesn't exist, you'll receive a 403 Forbidden error.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegated (personal Microsoft account)	Files.ReadWrite.AppFolder, Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Application	Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

HTTP Request

GET /me/drive/special/{special-folder-name}

Special folder names

The follow special folder names are available in OneDrive and OneDrive for Business.

Name	Folder id	Description
App Root	`approot`	The application's personal folder. Usually in `/Apps/{Application Name}`
Camera Roll	`cameraroll`	The Camera Roll Backup folder.
Desktop	`desktop`	The Desktop folder.
Documents	`documents`	The Documents folder.
Music	`music`	The Music folder.
Photos	`photos`	The Photos folder.

Optional query parameters

This method supports the $expand and $select OData query parameters to customize the response.

HTTP Response

This method returns a 200 OK response code and a driveItem object in the response body.

You can use this method of addressing a special folder inline with additional calls to properties or relationships on the driveItem.

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": "0123456789abc",
  "name": "Documents",
  "eTag": "012345819293.1",
  "specialFolder": {
    "name": "documents"
  }
}

Get children of a special folder

To request the children of a special folder, you can request the children collection or use the expand option to expand the children collection.

HTTP request

GET /me/drive/special/{special-folder-name}/children

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {"name": "myfile.jpg", "size": 2048 },
    {"name": "Documents", "folder": { "childCount": 4} },
    {"name": "Photos", "folder": { "childCount": 203} },
    {"name": "my sheet(1).xlsx", "size": 197 }
  ]
}

Remarks

Note: DriveItems with the specialFolder facet indicate the item is a special folder and can be accessed via the special collection.

If your app has read-only permissions, the request to get a special folder or the children of a special folder may fail with a 404 Not Found or a 403 Forbidden error if the special folder does not already exist.

Share via