OneDrive File Management

OneDrive File Management

OneDrive Overview

Microsoft OneDrive provides personal and business cloud file storage integrated with Microsoft 365. The Microsoft Graph API exposes full programmatic control over OneDrive content.

OneDrive Personal is tied to a Microsoft Account (consumer). OneDrive for Business is tied to a Microsoft 365 work or school account and backed by SharePoint document libraries. While both use the same Graph API surface, business accounts have additional admin controls, retention policies, and compliance features.

Microsoft Graph API — Drive Endpoints

Base URL: https://graph.microsoft.com/v1.0

Drive Discovery

Item Operations

Upload Patterns

Simple upload (< 4 MB):

PUT /me/drive/items/{parentId}:/{filename}:/content
Content-Type: application/octet-stream

<file bytes>

Resumable upload (> 4 MB, up to 250 GB):

1. Create upload session: POST /me/drive/items/{parentId}:/{filename}:/createUploadSession
2. Upload chunks with PUT to the returned uploadUrl, using Content-Range headers.
3. Chunk size must be a multiple of 320 KiB (327,680 bytes). Recommended: 5-10 MB per chunk.
4. On final chunk, the API returns the completed driveItem.

Upload to path:

PUT /me/drive/root:/path/to/file.txt:/content

Sharing

Sharing link types: view (read-only), edit (read-write), embed (embeddable). Scope: anonymous (anyone with link), organization (org members only), users (specific people).

Delta Queries (Change Tracking)

Track changes to a drive or folder over time:

GET /me/drive/root/delta

Returns a list of changed items and a @odata.deltaLink. Store the deltaLink and use it on subsequent calls to get only changes since the last query. This is the foundation for building sync clients.

Search

GET /me/drive/root/search(q='quarterly report')

Searches file names, metadata, and file content (for indexed types like Office documents and PDFs). Results include @search.score for relevance ranking. Supports KQL (Keyword Query Language) in OneDrive for Business.

Authentication & Scopes

OneDrive operations require these Microsoft Graph delegated permissions:

For application-level access (daemon/service), use Files.ReadWrite.All as an application permission with admin consent.

Common Patterns

Pagination

List operations return pages of results. Check for @odata.nextLink in the response and follow it to get subsequent pages. Default page size is 200 items.

Conflict Handling

Upload and move operations support @microsoft.graph.conflictBehavior:

• rename — Auto-rename the new item (e.g., file (1).txt)
• replace — Overwrite the existing item
• fail — Return a 409 Conflict error

Thumbnails

Get thumbnails for image and document files:

GET /me/drive/items/{itemId}/thumbnails

Returns small, medium, and large thumbnail URLs.

Special Folders

Access well-known folders:

GET /me/drive/special/{name}

Names: documents, photos, cameraroll, approot, music.

Best Practices

• Always use resumable upload for files over 4 MB to handle network interruptions.
• Use delta queries instead of full re-listing for sync scenarios — dramatically reduces API calls.
• Cache the deltaLink between sync cycles.
• Use $select to request only needed properties and reduce payload size.
• Use $expand=children sparingly — prefer explicit children listing for large folders.
• Set appropriate conflict behavior on uploads to avoid accidental overwrites.
• For batch operations, use the Microsoft Graph JSON batching endpoint (POST /$batch) to send up to 20 requests in a single HTTP call.

Reference Files

Example Files

Progressive Disclosure — Reference Files