Get a special folder by name

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

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.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegated (personal Microsoft account) Files.ReadWrite.AppFolder Files.Read, Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All
Application Not supported. Not supported.

HTTP Request

GET /me/drive/special/{name}

Special folder names

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

Name Folder ID Description
Documents documents The Documents folder.
Photos photos The Photos folder.
Camera Roll cameraroll The Camera Roll Backup folder.
App Root approot The application's personal folder. Usually in /Apps/{Application Name}.
Music music The Music folder.
Recordings recordings The Recordings folder. This option is only available in OneDrive for Business and SharePoint Online.

Optional query parameters

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

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.

Examples

Example 1: Get special folder by name

Request

GET /me/drive/special/{name}

Response

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

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

Example 2: 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.

Request

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

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.