Get a special folder by name

Article
10/27/2023

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}


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Special["{driveItem-id}"].GetAsync();

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta drives special get --drive-id {drive-id} --drive-item-id {driveItem-id}

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
special, err := graphClient.Drives().ByDriveId("drive-id").Special().ByDriveItemId("driveItem-id").Get(context.Background(), nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.drives().byDriveId("{drive-id}").special().byDriveItemId("{driveItem-id}").get();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/special/{name}')
	.version('beta')
	.get();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->drives()->byDriveId('drive-id')->special()->byDriveItemId('driveItem-id')->get()->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Files

Get-MgBetaDriveSpecial -DriveId $driveId -DriveItemId $driveItemId

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.drives.by_drive_id('drive-id').special.by_drive_item_id('driveItem-id').get()

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

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

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

let children = await client.api('/me/drive/special/{name}/children')
	.version('beta')
	.get();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Snippet not available

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

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

Get a special folder by name

Permissions

HTTP Request

Special folder names

Optional query parameters

Response

Examples

Example 1: Get special folder by name

Request

Response

Example 2: Get children of a special folder

Request

Response

Remarks

Feedback

Additional resources