Working with SharePoint site resources

2021-09-29

The SharePoint API in Microsoft Graph supports the following core scenarios:

Access to SharePoint sites, lists, and drives (document libraries)
Read-only support for site resources (no ability to create new sites)
Read-write support for lists, listItems, and driveItems
Address resources by SharePoint ID, URL, or relative path

The SharePoint API exposes three major resource types:

Site (this object)
List
ListItem

Tasks

All examples below are relative to https://graph.microsoft.com/v1.0.

Task name	Example Request
Get root site	GET /sites/root
Get site	GET /sites/{site-id}
Get site by path	GET /sites/{hostname}:/{site-path}
Get site for a group	GET /groups/{group-id}/sites/root
Search for sites	GET /sites?search={query}
Access the default document library for a site	GET /sites/{site-id}/drive
Enumerate the collection of document libraries under site	GET /sites/{site-id}/drives
Enumerate the lists under a site	GET /sites/{site-id}/lists
List root sites	GET /sites?filter=root ne null&select=siteCollection,webUrl
Search for sites	GET /sites?search={query}

Sites can also be addressed by path by using the SharePoint hostname, followed by a colon and the relative path to the site. You can optionally transition back to addressing the resource model by putting another colon at the end.

Path	Description
/sites/contoso.sharepoint.com:/teams/hr	The site associated with `https://contoso.sharepoint.com/teams/hr`
/sites/contoso.sharepoint.com:/teams/hr:/drive	Access the default drive for this site.

JSON representation

Here is a JSON representation of a site resource.

The site resource is derived from baseItem and inherits properties from that resource.

{
  "id": "string",
  "root": { "@odata.type": "microsoft.graph.root" },
  "sharepointIds": { "@odata.type": "microsoft.graph.sharepointIds" },
  "siteCollection": {"@odata.type": "microsoft.graph.siteCollection"},
  "displayName": "string",

  /* relationships */
  "contentTypes": [ { "@odata.type": "microsoft.graph.contentType" }],
  "drive": { "@odata.type": "microsoft.graph.drive" },
  "drives": [ { "@odata.type": "microsoft.graph.drive" }],
  "items": [ { "@odata.type": "microsoft.graph.baseItem" }],
  "lists": [ { "@odata.type": "microsoft.graph.list" }],
  "sites": [ { "@odata.type": "microsoft.graph.site"} ],
  "columns": [ { "@odata.type": "microsoft.graph.columnDefinition" }],

  /* inherited from baseItem */
  "name": "string",
  "createdDateTime": "datetime",
  "description": "string",
  "eTag": "string",
  "lastModifiedDateTime": "datetime",
  "webUrl": "url"
}

Properties

Property name	Type	Description
id	string	The unique identifier of the item. Read-only.
createdDateTime	DateTimeOffset	The date and time the item was created. Read-only.
description	string	The descriptive text for the site.
eTag	string	ETag for the item. Read-only.
displayName	string	The full title for the site. Read-only.
lastModifiedDateTime	DateTimeOffset	The date and time the item was last modified. Read-only.
name	string	The name / title of the item.
root	root	If present, indicates that this is the root site in the site collection. Read-only.
sharepointIds	sharepointIds	Returns identifiers useful for SharePoint REST compatibility. Read-only.
siteCollection	siteCollection	Provides details about the site's site collection. Available only on the root site. Read-only.
webUrl	string (url)	URL that displays the item in the browser. Read-only.

Relationships

Relationship name	Type	Description
columns	Collection(columnDefinition)	The collection of column definitions reusable across lists under this site.
contentTypes	Collection(contentType)	The collection of content types defined for this site.
drive	drive	The default drive (document library) for this site.
drives	Collection(drive)	The collection of drives (document libraries) under this site.
items	Collection(baseItem)	Used to address any item contained in this site. This collection cannot be enumerated.
lists	Collection(list)	The collection of lists under this site.
sites	Collection(site)	The collection of the sub-sites under this site.

Note for existing SharePoint developers

The Microsoft Graph SharePoint API has a few key differences with the CSOM APIs. The site resource maps to SPWeb. The root site (SPWeb) in a site collection has a siteCollection facet, which contains information about the SPSite. Because IDs for sites are only unique within their site collection, addressing a site by ID requires providing both the site collection identifier and the site identifier.

GET https://graph.microsoft.com/v1.0/sites/{hostname},{spsite-id},{spweb-id}/

A URL constructed with only the hostname will point to the root site (SPWeb) in the default site collection.

GET https://graph.microsoft.com/v1.0/sites/{hostname}

A URL constructed with only the hostname and siteCollection (SPSite) ID will point to the root site (SPWeb) in the given site collection.

GET https://graph.microsoft.com/v1.0/sites/{hostname},{spsite-id}

Share via