Microsoft Graph / OneDrive for Business: Does PUT /content guarantee atomic create-if-absent?

Product: Microsoft Graph API – OneDrive for Business / SharePoint Online

Subject: Does PUT /content with conflictBehavior=fail guarantee atomic file creation under concurrent requests?

Background

We are developing an iOS application that uses OneDrive for Business as a storage provider.

Our storage protocol requires a small JSON file to act as a canonical commit record. The file is created at a fixed path and must never be overwritten by a competing creation operation.

The required behavior is equivalent to an atomic create-if-absent operation.

We currently use Microsoft Graph upload sessions with conflictBehavior=fail.

During physical testing against OneDrive for Business, we observed HTTP 409 Conflict during concurrent upload-session creation for the same previously nonexistent filename, before either session had completed its upload.

At that point, neither listing the parent folder's children nor looking up the destination file by path returned a committed file.

This creates an ambiguity: the competing upload session may subsequently complete successfully, fail, be cancelled, or expire.

We are therefore evaluating the single-request small-file upload endpoint as an alternative.

Proposed API operation

PUT https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{parent-id}:/anchor-v1.json:/[email protected]=fail
Authorization: Bearer {access-token}
Content-Type: application/json

{ "example": "commit-record" }

The actual JSON file is small, typically well below 1 MB.

Questions

1. Atomic concurrent creation

Assume the destination file does not initially exist.

Two independent clients, potentially on different devices, simultaneously issue the above PUT request to the same parent folder and filename, with different file contents.

Does Microsoft Graph guarantee that:

At most one request creates the destination file?

The destination file is never overwritten or automatically renamed?

The losing request receives a definitive conflict response?

The conflict response means that a committed destination file exists, rather than merely that another request is temporarily in progress?

2. Failure or cancellation of the competing request

Suppose client A and client B issue concurrent requests.

Client A encounters a conflict while client B's request is still being processed.

If client B subsequently fails, is cancelled, or never commits the file, can client A nevertheless receive HTTP 409 / nameAlreadyExists?

In other words, can a small-file PUT return a name conflict based solely on an internal temporary reservation that never results in a committed DriveItem?

3. Structured error responses

For the above endpoint with conflictBehavior=fail:

What HTTP status and structured Microsoft Graph error.code are returned when the destination file already exists?

Can a concurrent in-progress creation produce a different status or error code?

Is nameAlreadyExists guaranteed to indicate an already committed destination file?

Are there other possible HTTP 409 conflict conditions that clients must distinguish?

4. Conditional create using If-None-Match

Does the small-file PUT endpoint support:

If-None-Match: *

If supported, is this condition evaluated atomically against the destination file's existence across concurrent requests, including requests from different devices?

What response is guaranteed when the condition fails?

5. Visibility and ambiguous responses

After a successful 201 Created response:

Is the newly created DriveItem guaranteed to be immediately accessible through a direct path lookup?

Is it immediately accessible through an item-ID lookup?

Can parent-folder children enumeration temporarily disagree with direct lookup?

Are any consistency or visibility guarantees documented?

If a client loses its network connection after sending the PUT request but before receiving the response, is there a documented recovery or reconciliation procedure for determining whether that particular request committed?

6. Supported conflict-behavior syntax

Please confirm that @microsoft.graph.conflictBehavior=fail is supported for the exact small-file PUT endpoint shown above on OneDrive for Business.

The DriveItem resource documentation describes this parameter, but the method-specific driveitem-put-contentdocumentation does not explicitly describe its concurrent creation semantics.

Required correctness property

Our storage protocol must not report a successful commit unless the canonical file was actually created and validated.

It must also never interpret a temporary competing operation as proof that a committed file already exists.

We need a server-side atomic create-if-absent primitive that remains correct across independent clients, process crashes, cancellations, and network interruptions.

We can handle an ambiguous network response conservatively, but we cannot rely on undocumented timing assumptions, fixed delays, or repeated polling to establish whether a competing operation committed.

Could you confirm whether the proposed small-file PUT operation provides these guarantees?

If it does not, is there another supported Microsoft Graph / OneDrive for Business API operation that provides atomic create-if-absent semantics for a file at a fixed path?

We would appreciate references to the applicable API contract or documentation, particularly concerning concurrent requests and conflict handling.

Relevant Microsoft documentation

Upload or replace DriveItem content

DriveItem resource and conflict behavior

Create upload session

• OneDrive error responses