A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The OneDrive API is how an app or AI agent works with the files in a OneDrive or SharePoint document library: reading a folder's contents, uploading and updating files, moving and copying items, searching across a drive, and sharing a file with someone. Access is granted through an OAuth token and a set of permissions that decide what each call can read or write, and an agent is limited to the drives and items that token reaches. It can also push a change notification when something changes under a folder, so an agent can react instead of polling.
How an app or AI agent connects to OneDrive determines what it can reach. Access runs through Microsoft Graph, governed by the token behind the call and the permissions that token carries.
The files surface answers under the Microsoft Graph v1.0 endpoint at https://graph.microsoft.com/v1.0, with drives reached as /me/drive or /drives/{drive-id} and items as driveItem resources. This is the main way an app or AI agent works with OneDrive and SharePoint files.
A subscription tells Microsoft Graph to post to a receiver URL when something changes under a subscribed drive folder. The notification reports only that a change occurred, so the app then calls the change-tracking method to read what changed.
Microsoft's first-party Model Context Protocol server at https://mcp.svc.cloud.microsoft/enterprise translates natural-language requests into read-only Microsoft Graph calls. In public preview it is scoped to Microsoft Entra identity and directory data, not the OneDrive files surface, so it does not yet cover drive items.
An OAuth token obtained on behalf of a signed-in user. The app can never see more than that user can, so a delegated token scoped to Files.Read reaches only that user's own OneDrive. This is the least-privilege route for acting as a specific person.
An OAuth token the app obtains as itself, with no user signed in, using application permissions granted by an administrator. It suits background automation but reaches whatever the granted .All scope allows across the tenant, and new external guests can't be invited with it.
The OneDrive API is split into areas an agent can act on, such as drives, files and folders, file content, search, and sharing. Each area has its own methods and its own permissions, and some grant access to far more than others.
Read a drive's metadata, list the drives available to a user, group, or site, and get a drive's root folder.
Get an item, list a folder's children, create a folder, update an item, delete it, and move or copy items.
Download a file's bytes, upload a small file in one call, and create an upload session for large files.
Search a drive for matching items, track changes since the last run, and list an item's thumbnails.
Create a sharing link, invite specific people to an item, list its permissions, and remove a permission.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
DrivesRead a drive's metadata, list the drives available to a user, group, or site, and get a drive's root folder.3 | ||||||
| GET | /me/drive | Get metadata about a drive, such as the signed-in user's OneDrive. | read | Files.Read | Current | |
Also reachable as /drives/{drive-id}, /sites/{site-id}/drive, and /users/{user-id}/drive. Application access uses Files.Read.All; SharePoint libraries may need Sites.Read.All. Acts ondrive Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sites/{site-id}/drives | List the drives available to a user, group, or site. | read | Files.Read.All | Current | |
Also reachable as /me/drives, /users/{user-id}/drives, and /groups/{group-id}/drives. SharePoint sites may need Sites.Read.All. Acts ondrive Permission (capability) Files.Read.AllVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/drive/root | Get the root folder of a drive. | read | Files.Read | Current | |
The root is a driveItem like any other folder. Application access uses Files.Read.All. Acts ondriveItem Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limit1 resource unit SourceOfficial documentation ↗ | ||||||
Files & foldersGet an item, list a folder's children, create a folder, update an item, delete it, and move or copy items.7 | ||||||
| GET | /me/drive/items/{item-id} | Get the metadata for a file, folder, or other item by id or path. | read | Files.Read | Current | |
Also addressable by path as /me/drive/root:/{item-path}. Application access uses Files.Read.All; SharePoint may need Sites.Read.All. Acts ondriveItem Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limit1 resource unit SourceOfficial documentation ↗ | ||||||
| GET | /me/drive/items/{item-id}/children | List the immediate children of a folder. | read | Files.Read | Current | |
Root children list as /me/drive/root/children. A multi-item query. Application access uses Files.Read.All. Acts ondriveItem Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limit2 resource units SourceOfficial documentation ↗ | ||||||
| POST | /me/drive/items/{parent-item-id}/children | Create a new folder, or another driveItem, under a parent folder. | write | Files.ReadWrite | Current | |
Send a body with a folder facet. The @microsoft.graph.conflictBehavior value controls naming when one already exists. Application access uses Files.ReadWrite.All. Acts ondriveItem Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook event driveitem-changedRate limit2 resource units SourceOfficial documentation ↗ | ||||||
| PATCH | /me/drive/items/{item-id} | Update an item's metadata, such as renaming a file or folder. | write | Files.ReadWrite | Current | |
Updates metadata, not content; use the content method to change bytes. Application access uses Files.ReadWrite.All. Acts ondriveItem Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook event driveitem-changedRate limit2 resource units SourceOfficial documentation ↗ | ||||||
| DELETE | /me/drive/items/{item-id} | Delete a file or folder, sending it to the recycle bin. | write | Files.ReadWrite | Current | |
Deleting a folder removes its contents too. Application access uses Files.ReadWrite.All. Acts ondriveItem Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook event driveitem-changedRate limit2 resource units SourceOfficial documentation ↗ | ||||||
| PATCH | /me/drive/items/{item-id} | Move an item to a new parent folder by updating its parentReference. | write | Files.ReadWrite | Current | |
A move is a PATCH that sets a new parentReference, optionally with a new name. Application access uses Files.ReadWrite.All. Acts ondriveItem Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook event driveitem-changedRate limit2 resource units SourceOfficial documentation ↗ | ||||||
| POST | /me/drive/items/{item-id}/copy | Create a copy of an item, including any children, in a chosen location. | write | Files.ReadWrite | Current | |
Runs in the background; the response gives a URL to monitor progress rather than the finished item. Application access uses Files.ReadWrite.All. Acts ondriveItem Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook event driveitem-changedRate limit2 resource units SourceOfficial documentation ↗ | ||||||
File contentDownload a file's bytes, upload a small file in one call, and create an upload session for large files.3 | ||||||
| GET | /me/drive/items/{item-id}/content | Download the bytes of a file. | read | Files.Read | Current | |
Redirects to a short-lived pre-authenticated download URL that needs no further token for about an hour. Application access uses Files.Read.All. Acts ondriveItem Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limit1 resource unit SourceOfficial documentation ↗ | ||||||
| PUT | /me/drive/items/{parent-id}:/{filename}:/content | Upload a new file, or replace an existing file's content, in a single call. | write | Files.ReadWrite | Current | |
Supports files up to 250 MB; larger files use an upload session. Replace an existing file as /me/drive/items/{item-id}/content. Application access uses Files.ReadWrite.All. Acts ondriveItem Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook event driveitem-changedRate limit2 resource units SourceOfficial documentation ↗ | ||||||
| POST | /me/drive/items/{parent-id}:/{filename}:/createUploadSession | Create an upload session to send a large file in resumable byte ranges. | write | Files.ReadWrite | Current | |
Each range is up to 60 MiB and, except the last, a multiple of 320 KiB. Application-only access uses Sites.ReadWrite.All, not Files.ReadWrite.All. Acts onuploadSession Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook event driveitem-changedRate limit2 resource units SourceOfficial documentation ↗ | ||||||
Search & change trackingSearch a drive for matching items, track changes since the last run, and list an item's thumbnails.4 | ||||||
| GET | /me/drive/root/search(q='{search-text}') | Search a drive's hierarchy for items matching a query across filename, metadata, and content. | read | Files.Read | Current | |
Searching from /me/drive/search instead also returns items shared with the user. Doesn't support the Sites.Selected application permission. Application access uses Files.Read.All. Acts ondriveItem Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limit2 resource units SourceOfficial documentation ↗ | ||||||
| GET | /me/drive/root/delta | Track changes in a drive over time, returning items added, changed, or removed since the last run. | read | Files.Read | Current | |
Ends a run with an @odata.deltaLink to replay later. Costs 1 unit when called with a token, 2 without. Application access uses Files.Read.All. Acts ondriveItem Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limit1 resource unit (with token) SourceOfficial documentation ↗ | ||||||
| GET | /me/drive/items/{item-id}/thumbnails | List the thumbnail images generated for an item. | read | Files.Read | Current | |
Returns small, medium, and large sizes where available. Application access uses Files.Read.All. Acts onthumbnailSet Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /subscriptions | Create a change-notification subscription so Graph posts to a receiver URL when something changes under a drive folder. | write | Files.Read | Current | |
Subscribe with a resource of me/drive/root or a subfolder (personal) or the root only (Business). Needs read permission on the resource: delegated Files.Read on personal, Files.Read.All on Business and for application access. Acts onsubscription Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook event driveitem-changedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sharing & permissionsCreate a sharing link, invite specific people to an item, list its permissions, and remove a permission.4 | ||||||
| POST | /me/drive/items/{item-id}/createLink | Create a sharing link to a file or folder, as a view, edit, or embed link. | write | Files.ReadWrite | Current | |
The scope value sets reach: anonymous (anyone with the link), organization (anyone signed in to the tenant), or users (named people). A permission operation. Application access uses Files.ReadWrite.All. Acts onpermission Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limit5 resource units SourceOfficial documentation ↗ | ||||||
| POST | /me/drive/items/{item-id}/invite | Send a sharing invitation that grants named recipients read or write access to an item. | write | Files.ReadWrite | Current | |
Permissions can't be set on the root of a personal OneDrive, and new external guests can't be invited with an application-only token. Application access uses Files.ReadWrite.All. Acts onpermission Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limit5 resource units SourceOfficial documentation ↗ | ||||||
| GET | /me/drive/items/{item-id}/permissions | List the sharing permissions currently set on an item. | read | Files.Read | Current | |
Shows links and direct grants on the item. A permission operation. Application access uses Files.Read.All. Acts onpermission Permission (capability) Files.ReadVersionAvailable since the API’s base version Webhook eventNone Rate limit5 resource units SourceOfficial documentation ↗ | ||||||
| DELETE | /me/drive/items/{item-id}/permissions/{perm-id} | Remove a sharing permission from an item, revoking that access. | write | Files.ReadWrite | Current | |
Deletes one link or grant by its permission id. A permission operation. Application access uses Files.ReadWrite.All. Acts onpermission Permission (capability) Files.ReadWriteVersionAvailable since the API’s base version Webhook eventNone Rate limit5 resource units SourceOfficial documentation ↗ | ||||||
Microsoft Graph can notify an app or AI agent when something changes in a drive, instead of the app repeatedly asking. A change notification says only that something changed under the subscribed folder, and the agent then calls the change-tracking method to read the details.
| Event | What it signals | Triggered by |
|---|---|---|
driveItem change notification | Fires when an item is created, updated, or deleted under a subscribed drive folder. The notification reports only that a change happened, not the detail, so the receiver calls the change-tracking method to read exactly which items changed. On personal OneDrive a subscription can target the root or any subfolder; on OneDrive for Business only the root. | /me/drive/items/{parent-item-id}/children/me/drive/items/{item-id}/me/drive/items/{parent-id}:/{filename}:/content/me/drive/items/{item-id}/me/drive/items/{item-id}/me/drive/items/{item-id}/copy |
OneDrive limits how much an app or AI agent can call through a resource-unit budget rather than a simple request count, where each kind of call costs a set number of units against a per-app and per-user ceiling over a time window.
OneDrive and SharePoint throttle by a resource-unit budget rather than a raw request count, where each call has a set cost: a single-item read such as getting an item, a download, or a delta call with a token costs 1 unit, a multi-item call such as listing children or any create, update, delete, or upload costs 2 units, and any permission call costs 5 units. Those units are charged against several ceilings at once, including a per-user limit of 3,000 requests every 5 minutes and a per-app, per-tenant limit that scales with the tenant's license count, from 1,250 resource units a minute at the smallest tier up to 6,250 at the largest, plus a separate 24-hour app ceiling. Going over returns HTTP 429 Too Many Requests, or 503 when the service is overloaded, both carrying a Retry-After header in seconds that should be honored before retrying. RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers give an early warning as an app nears its per-minute budget.
List, search, and change-tracking responses page through an @odata.nextLink URL: an app follows that link until it stops being returned, rather than building the URL by hand. The $top query parameter sets the page size, and search also accepts a $skipToken. Change tracking ends a run with an @odata.deltaLink instead of a nextLink, which is saved and replayed later to read only what changed since.
A single-call upload through the content method handles files up to 250 MB. Larger files go through an upload session, which takes the file in sequential byte ranges of up to 60 MiB each, where every range except the last must be a multiple of 320 KiB. A sharing-invitation message is capped at 2,000 characters. Exceeding the drive's storage quota returns HTTP 507 Insufficient Storage.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | InvalidAuthenticationToken | The required authentication information is missing or the token is invalid or expired. | Acquire a fresh OAuth token and resend it in the Authorization header. |
| 403 | accessDenied | The caller is authenticated but the token lacks the permission, or the user lacks the rights, to act on this item. | Grant the missing scope, such as Files.ReadWrite.All, or use an account with access to the item. |
| 404 | itemNotFound | The requested item doesn't exist, or the token can't see it. Graph returns 404 rather than 403 when access is the reason, so it doesn't confirm a hidden item exists. | Confirm the drive and item id or path, and that the token has access to the item. |
| 409 | nameAlreadyExists | The request conflicts with the current state, most often an item with the same name already exists at the destination. | Set the @microsoft.graph.conflictBehavior value to rename or replace, or choose a different name. |
| 412 | preconditionFailed | An if-match or if-none-match eTag sent with the request doesn't match the item's current state. | Refetch the item to read its current eTag, then retry with the updated precondition. |
| 423 | locked | The item is locked, for example checked out by another user, and can't be changed. | Wait for the lock to clear or check the item back in, then retry. |
| 429 | activityLimitReached | The app or user exceeded a resource-unit budget and is being throttled. SharePoint returns 429, or 503 when the service is overloaded. | Honor the Retry-After header in seconds before retrying, and slow down as RateLimit headers near zero. |
| 507 | quotaLimitReached | The upload would exceed the drive's storage quota. | Free space in the drive or target a drive with available quota, then retry. |
Microsoft Graph serves two named endpoints, the stable v1.0 endpoint and a separate beta endpoint. The OneDrive files surface lives on v1.0, where individual methods are added and changed over time rather than the whole endpoint being re-versioned.
The OneDrive and SharePoint files surface, built on the driveItem resource, is served on the stable v1.0 Microsoft Graph endpoint. Microsoft adds and adjusts individual methods over time and records each change in the Microsoft Graph changelog rather than re-versioning the whole endpoint. The beta endpoint carries preview features that aren't guaranteed stable.
Microsoft published its first-party MCP server, the Microsoft MCP Server for Enterprise, in public preview. It translates natural-language requests into read-only Microsoft Graph calls and is currently scoped to Microsoft Entra identity and directory data, not the OneDrive files surface. It is documented as a preview product that may change before release.
An integration calls the v1.0 endpoint for production work and tracks individual method changes through the Microsoft Graph changelog.
Microsoft Graph changelog ↗Bollard AI sits between a team's AI agents and OneDrive. Grant each agent exactly the access it needs, read or write, folder by folder, and every call is checked and logged.