An API that connects multiple Microsoft services, enabling data access and automation across platforms
The public Microsoft Graph v1.0 contract does not document a OneDrive Personal deferred-commit operation that both targets an existing item by ID and atomically revalidates that item’s eTag at publication, so the tested flow cannot currently provide the synchronization guarantee you require.
Documented deferred completion request
For OneDrive Personal, the upload-session documentation says that after all ranges have been uploaded with deferCommit: true, completion uses a final metadata PUT; the zero-length POST alternative is supported only by OneDrive for Business and SharePoint. The documented PUT is addressed to the destination parent path, not to /items/{existing-item-id} or /content:^1^
PUT https://graph.microsoft.com/v1.0/me/drive/root:/{path_to_parent}
Authorization: Bearer {token}
Content-Type: application/json
If-Match: {etag-or-ctag}
{
"name": "file.dat",
"@microsoft.graph.conflictBehavior": "replace",
"@microsoft.graph.sourceUrl": "{uploadUrl}"
}
The same page says @microsoft.graph.sourceUrl identifies the existing upload session and explicitly shows conflict behavior in the JSON body. However, the DriveItem instance-attribute page says conflict behavior should be placed in the URL rather than the body. It describes conflict behavior as applying to actions that create a new item, while sourceUrl instructs the service to fetch URL content during a PUT.^2^
That is a documentation inconsistency. Neither page publishes:
- an equivalent final
PUTaddressed to/me/drive/items/{existing-item-id}; - a schema requiring
sourceUrlto be adata:URI; - a OneDrive Personal request guaranteed to replace that exact item while retaining its ID.
Consequently, the invalidRequest/data-URI response cannot be authoritatively explained from the published contract. Adding an empty file facet is not documented as part of this request and should not be relied upon. Your parent-path request most closely matches the example, but its failure requires service-side investigation rather than another payload variation.
eTag and atomicity boundaries
If-Match is explicitly documented for creating the upload session:
POST /me/drive/items/{item-id}/createUploadSession
If-Match: E1
Content-Type: application/json
{
"deferCommit": true,
"item": {
"@microsoft.graph.conflictBehavior": "replace"
}
}
A mismatch at that point returns 412 Precondition Failed.^1^
The documentation does not state that this precondition is retained and re-evaluated when a deferred session is committed. Although the explicit-commit example says If-Match can be used, it does not define:
- whether the compared eTag belongs to the parent or an existing child;
- whether the comparison and content publication are atomic;
- whether a rename, move, delete, or delete-and-recreate invalidates publication;
- whether successful
replacepreserves an existing item ID.
Your parent-folder result is consistent with the header being evaluated against the addressed resource: a file eTag yielded 412, while the parent eTag passed that check and reached later request validation. That remains observed behavior, not a documented child-item concurrency guarantee.
The DriveItem model distinguishes eTag—metadata plus content—from cTag, which represents content and does not change for metadata-only updates.^2^ No retrieved contract maps either tag to an atomic deferred publication check for an existing Personal item.
Therefore, no documented status-code matrix guarantees non-publication for every concurrent modification, rename, move, deletion, or recreation case. A 412 guarantees that the documented precondition failed for the request/resource on which it is supported; it does not establish which child version was protected by the parent-addressed commit.
Lost responses and session lifetime
Persist the opaque uploadUrl, expirationDateTime, target item ID, original eTag, expected size, and expected hash before uploading. After a disconnect or restart:
- Send
GET {uploadUrl}to retrieve missing ranges and the current expiration time. - If the session is still pending and publication must be prevented, send:
DELETE {uploadUrl}
A successful cancellation returns 204 No Content and cleans up the temporary uploaded data. Uncommitted fragments are discarded after session expiration, although temporary-file deletion might not occur immediately.^1^ Each uploaded fragment extends the expiration time, which is why the latest returned value—not only the initial value—must be persisted.^3^
The documentation does not define cancellation as a barrier against a commit request already in flight, nor does it provide an idempotency key or terminal “committed versus cancelled” receipt. After an ambiguous final response, reconcile both:
- the session state through its upload URL; and
- the target DriveItem by ID, comparing its eTag, size, and expected content hash.
That can establish observed final state, but the published API does not provide a proof that an already accepted delayed request can never publish later. If that proof is mandatory, deferred commit on OneDrive Personal is not a sufficient documented protocol.
Direct /content replacement
The documented direct replacement operation is:
PUT /me/drive/items/{item-id}/content
Authorization: Bearer {token}
Content-Type: application/octet-stream
<replacement bytes>
It supports files up to 250 MB and returns the updated DriveItem.^4^ Its request-header table does not list If-Match. Therefore, observed 412 responses with stale eTags are useful implementation evidence but are not a published atomic-concurrency guarantee for OneDrive Personal, OneDrive for Business, or SharePoint. No product-specific difference in that guarantee is documented on this endpoint.
For a contractual answer covering atomic publication, item-ID preservation, races, and ambiguous completion, open a Microsoft Graph support case and include the sanitized requests, timestamps, drive type, request IDs, client-request IDs, and responses. Ask support to confirm whether the behavior is supported or incidental and to reconcile the contradiction between the upload-session example and the DriveItem annotation guidance.
References