driveItem resource

The driveItem resource represents an item in a drive. All top-level file system objects in OneDrive are returned as driveItem resources. They can be accessed by their id using the /items/{item-id} syntax, or by their file system path using the /drive/root:/path/to/file syntax.

DriveItems have facets that provide data about the item's identities and capabilities. Folders have a folder facet and files have a file facet. Images have an image facet in addition to their file facet.

DriveItems with the folder facet act as containers of items and therefore have a children reference pointing to a collection of items under the folder.

Tasks on driveItem resources

The following tasks are available for driveItem resources.

Common task HTTP method (by ID) HTTP method (by path)
Get metadata for an Item GET /drive/items/{id} GET /drive/root:/{path}
List an Item's children GET /drive/items/{id}/children GET /drive/root:/{path}:/children
Create a Folder POST /drive/items/{parent-id}/children POST /drive/root:/{parent-path}:/children
Upload an Item's contents PUT /drive/items/{parent-id}/children/{name}/content PUT /drive/root:/{parent-path}/{name}:/content
Update an Item's contents PATCH /drive/items/{id} PATCH /drive/root:/{path}
Delete an Item DELETE /drive/items/{id} DELETE /drive/root:/{path}
Move an Item PATCH /drive/items/{id} PATCH /drive/root:/{path}
Copy an Item POST /drive/items/{id}/copy POST /drive/root:/{path}:/copy
Download an Item's contents GET /drive/items/{id}/content GET /drive/root:/{path}:/content
Search for an Item GET /drive/items/{id}/search GET /drive/root:/{path}:/search
View changes on an Item GET /drive/items/{id}/delta GET /drive/root:/{path}:/delta
Get thumbnails for an Item GET /drive/items/{id}/thumbnails GET /drive/root:/{path}:/thumbnails
Sharing by link POST /drive/items/{id}/createLink POST /drive/root:/{path}:/createLink

JSON representation

Here is a JSON representation of a driveItem.

{
  "id": "string (identifier)",
  "name": "string",
  "eTag": "string (etag)",
  "cTag": "string (etag)",
  "createdBy": { "@odata.type": "oneDrive.identitySet" },
  "createdDateTime": "string (timestamp)",
  "lastModifiedBy": { "@odata.type": "oneDrive.identitySet" },
  "lastModifiedDateTime": "string (timestamp)",
  "size": 1024,
  "webUrl": "url",
  "webDavUrl": "url",
  "description": "string",
  "parentReference": { "@odata.type": "oneDrive.itemReference"},
  "folder": { "@odata.type": "oneDrive.folder" },
  "file": { "@odata.type": "oneDrive.file" },
  "fileSystemInfo": {"@odata.type": "oneDrive.fileSystemInfo"},
  "image": { "@odata.type": "oneDrive.image" },
  "photo": { "@odata.type": "oneDrive.photo" },
  "audio": { "@odata.type": "oneDrive.audio" },
  "video": { "@odata.type": "oneDrive.video" },
  "location": { "@odata.type": "oneDrive.location" },
  "remoteItem": { "@odata.type": "oneDrive.remoteItem"},
  "searchResult": { "@odata.type": "oneDrive.searchResult"},
  "deleted": { "@odata.type": "oneDrive.deleted"},
  "specialFolder": { "@odata.type": "oneDrive.specialFolder" },
  "shared": {"@odata.type": "oneDrive.shared" },
  "sharepointIds": {"@odata.type": "oneDrive.sharepointIds" },
  "root": { "@odata.type": "oneDrive.root" },
  "children": [ { "@odata.type": "oneDrive.item" } ],
  "thumbnails": [ {"@odata.type": "oneDrive.thumbnailSet"} ],
  "@microsoft.graph.conflictBehavior": "string",
  "@microsoft.graph.downloadUrl": "url",
  "@microsoft.graph.sourceUrl": "url",
  "content": { "@odata.type": "Edm.Stream" }
}

Properties

The Item object has these properties.

Property name Type Description
id String The unique identifier of the item within the Drive. Read-only.
audio AudioFacet Audio metadata, if the item is an audio file. Read-only.
createdBy IdentitySet Identity of the user, device, and application which created the item. Read-only.
createdDateTime DateTimeOffset Date and time of item creation. Read-only.
cTag String An eTag for the content of the item. This eTag is not changed if only the metadata is changed. Note This property is not returned if the Item is a folder. Read-only.
deleted DeletedFacet Information about the deleted state of the item. Read-only.
description String Provide a user-visible description of the item. Read-write.
eTag String eTag for the entire item (metadata + content). Read-only.
file FileFacet File metadata, if the item is a file. Read-only.
fileSystemInfo FileSystemInfoFacet File system information on client. Read-write.
folder FolderFacet Folder metadata, if the item is a folder. Read-only.
image ImageFacet Image metadata, if the item is an image. Read-only.
lastModifiedBy IdentitySet Identity of the user, device, and application which last modified the item. Read-only.
lastModifiedDateTime DateTimeOffset Date and time the item was last modified. Read-only.
location LocationFacet Location metadata, if the item has location data. Read-only.
name String The name of the item (filename and extension). Read-write.
package PackageFacet If present, indicates that this item is a package instead of a folder or file. Packages are treated like files in some contexts and folders in others.
parentReference ItemReference Parent information, if the item has a parent. Read-write.
photo PhotoFacet Photo metadata, if the item is a photo. Read-only.
remoteItem remoteItemFacet Remote item data, if the item is shared from a remote drive.
searchResult SearchResultFacet Search metadata, if the item is from a search result.
shared SharedFacet Indicates that the item has been shared with others and provides information about the shared state of the item. Read-only.
sharepointIds SharepointIdsFacet Access to the unique identifiers for this item via SharePoint REST API. Read-only.
size Int64 Size of the item in bytes. Read-only.
specialFolder SpecialFolderFacet If the current item is also available as a special folder, this facet is returned. Read-only.
root rootFacet If this property is non-null, it indicates that the driveItem is the top-most driveItem in the drive.
video VideoFacet Video metadata, if the item is a video. Read-only.
webDavUrl String DAV compatible URL for the item.
webUrl String URL that displays the resource in the browser. Read-only.

Note: The eTag and cTag properties work differently on containers (folders). The cTag value is modified when content or metadata of any descendant of the folder is changed. The eTag value is only modified when the folder's properties are changed, except for properties that are derived from descendants (like childCount or lastModifiedDateTime).

Instance Attributes

Instance attributes are properties with special behaviors. This properties are temporary and either a) define behavior the service should perform or b)provide short-term property values, like a download URL for an item that expires.

Property name Type Description
@microsoft.graph.conflictBehavior string The conflict resolution behavior for actions that create a new item. An item will never be returned with this annotation. Write-only.
@microsoft.graph.downloadUrl string A Url that can be used to download this file's content. Authentication is not required with this URL. Read-only.
@microsoft.graph.sourceUrl string When issuing a PUT request, this instance annotation can be used to instruct the service to download the contents of the URL, and store it as the file. Write-only.

Note: The @microsoft.graph.downloadUrl is a short-lived URL and can't be cached. The URL will only be available for a short period of time before it is invalidated.

Relationships

The following table defines the relationships that the driveItem resource has to other resources.

Relationship name Type Description
content Stream The content stream, if the Item represents a file.
children driveItem collection Collection containing Item objects for the immediate children of Item. Only items representing folders have children.
thumbnails ThumbnailSet collection Collection containing ThumbnailSet objects associated with the item. For more info, see getting thumbnails.

Remarks

In OneDrive for Business, the cTag property is not returned, if the driveItem is a folder.

In OneDrive Personal, the sharepointIds property is unavailable.