microsoftgraph · rykoma · Feb 12, 2026
diff --git a/api-reference/v1.0/api/driveitem-createuploadsession.md b/api-reference/v1.0/api/driveitem-createuploadsession.md
@@ -17,8 +17,8 @@ An upload session allows your app to upload ranges of the file in sequential API
 
 To upload a file using an upload session:
 
-1. [Create an upload session](#create-an-upload-session)
-2. [Upload bytes to the upload session](#upload-bytes-to-the-upload-session)
+1. [Create an upload session](#example-1-create-an-upload-session)
+2. [Upload bytes to the upload session](#example-2-upload-bytes-to-the-upload-session)
 
 [!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
 
@@ -31,18 +31,11 @@ Choose the permission or permissions marked as least privileged for this API. Us
 
 [!INCLUDE [app-permissions](../includes/sharepoint-embedded-app-driveitem-permissions.md)]
 
-## Create an upload session
-
-To begin a large file upload, your app must first request a new upload session.
-This request creates a temporary storage location where the bytes of the file are saved until the complete file is uploaded.
-When the last byte of the file is uploaded, the upload session is completed and the final file is shown in the destination folder.
-Alternatively, you can defer final creation of the file in the destination until you explicitly make a request to complete the upload, by setting the **deferCommit** property in the request arguments.
-
-### HTTP request
+## HTTP request
 
 To upload a new file, you must provide both the parent ID and the new file name in the request. However, an update only requires the ID of the item to be updated.
 
-#### Create new file
+### Create new file
 
 <!-- { "blockType": "ignored" } -->
 
@@ -54,7 +47,7 @@ POST /sites/{siteId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
 POST /users/{userId}/drive/items/{parentItemId}:/{fileName}:/createUploadSession
 ```
 
-#### Update existing file
+### Update existing file
 
 <!-- { "blockType": "ignored" } -->
 
@@ -66,14 +59,14 @@ POST /sites/{siteId}/drive/items/{itemId}/createUploadSession
 POST /users/{userId}/drive/items/{itemId}/createUploadSession
 ```
 
-### Request headers
+## Request headers
 
 | Name       | Value | Description                                                                                                                                                            |
 |:-----------|:------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | *if-match* | etag  | If this request header is included and the eTag (or cTag) provided doesn't match the current etag on the item, a `412 Precondition Failed` error response is returned. |
 | *if-none-match* | etag | If this request header is included and the eTag (or cTag) provided matches the current etag on the item, a `412 Precondition Failed` error response is returned. |
 
-### Request body
+## Request body
 
 No request body is required. However, you can specify properties in the request body to provide more information about the file being uploaded and to customize the semantics of the upload operation.
 
@@ -107,7 +100,32 @@ The following example controls the behavior if the filename is already taken. Th
 | deferCommit | Boolean                                                                        | If set to `true`, the final creation of the file in the destination requires an explicit request. |
 | item        | [driveItemUploadableProperties](../resources/driveItemUploadableProperties.md) | Data about the file being uploaded.                                                                   |
 
-### Request
+## Response
+
+If successful, the response to this request provides the details of where the remainder of the requests should be sent as an [uploadSession](../resources/uploadsession.md) resource.
+
+When a session is created and generates preauthenticated upload URLs, the upload URL can be used to complete the upload within a time window sufficient for large files.
+
+The [uploadSession](../resources/uploadsession.md) resource provides details about where each byte range of the file should be uploaded and specifies when the session expires. The **expirationDateTime** property indicates the time at which the current session expires if no further activity occurs. This results in the following behavior:
+
+- You must upload the next fragment or commit the session before the time specified in the **expirationDateTime** property.
+- Each uploaded fragment extends the expiration time, which allows large file uploads to be completed successfully. The updated expiration time is returned in every request to upload a file fragment.
+- If no fragments are received and the session isn't committed, all previously uploaded fragments are discarded.
+
+This process supports large file uploads and ensures that upload sessions are efficiently managed by preventing stale or abandoned data from remaining in the system too long.
+
+If the `fileSize` parameter is specified and exceeds the available quota, a `507 Insufficient Storage` response is returned and the upload session isn't created.
+
+## Examples
+
+### Example 1: Create an upload session
+
+To begin a large file upload, your app must first request a new upload session.
+This request creates a temporary storage location where the bytes of the file are saved until the complete file is uploaded.
+When the last byte of the file is uploaded, the upload session is completed and the final file is shown in the destination folder.
+Alternatively, you can defer final creation of the file in the destination until you explicitly make a request to complete the upload, by setting the **deferCommit** property in the request arguments.
+
+#### Request
 
 The response to this request provides the details of the newly created [uploadSession](../resources/uploadsession.md), which includes the URL used for uploading the parts of the file.
 
@@ -127,21 +145,7 @@ Content-Type: application/json
 }
 ```
 
-### Response
-
-If successful, the response to this request provides the details of where the remainder of the requests should be sent as an [uploadSession](../resources/uploadsession.md) resource.
-
-When a session is created and generates preauthenticated upload URLs, the upload URL can be used to complete the upload within a time window sufficient for large files.
-
-The [uploadSession](../resources/uploadsession.md) resource provides details about where each byte range of the file should be uploaded and specifies when the session expires. The **expirationDateTime** property indicates the time at which the current session expires if no further activity occurs. This results in the following behavior:
-
-- You must upload the next fragment or commit the session before the time specified in the **expirationDateTime** property.
-- Each uploaded fragment extends the expiration time, which allows large file uploads to be completed successfully. The updated expiration time is returned in every request to upload a file fragment.
-- If no fragments are received and the session isn't committed, all previously uploaded fragments are discarded.
-
-This process supports large file uploads and ensures that upload sessions are efficiently managed by preventing stale or abandoned data from remaining in the system too long.
-
-If the `fileSize` parameter is specified and exceeds the available quota, a `507 Insufficient Storage` response is returned and the upload session isn't created.
+#### Response
 
 <!-- { "blockType": "response", "@odata.type": "microsoft.graph.uploadSession",
        "optionalProperties": [ "nextExpectedRanges" ]  } -->
@@ -156,7 +160,7 @@ Content-Type: application/json
 }
 ```
 
-## Upload bytes to the upload session
+### Example 2: Upload bytes to the upload session
 
 To upload the file, or a portion of the file, your app makes a PUT request to the **uploadUrl** value received in the **createUploadSession** response.
 You can upload the entire file, or split the file into multiple byte ranges, as long as the maximum bytes in any given request is less than 60 MiB.
@@ -168,7 +172,7 @@ Uploading fragments out of order results in an error.
 
 Using a fragment size that doesn't divide evenly by 320 KiB results in errors committing some files.
 
-### Example
+#### Request
 
 In this example, the app is uploading the first 26 bytes of a 128-byte file.
 
@@ -191,7 +195,7 @@ Content-Range: bytes 0-25/128
 > - To upload large files using SDKs, see [Upload large files using the Microsoft Graph SDKs](/graph/sdks/large-file-upload).
 > - Your app must ensure the total file size specified in the `Content-Range` header is the same for all requests. If a byte range declares a different file size, the request fails.
 
-### Response
+#### Response
 
 When the request is complete, the server responds with `202 Accepted` if there are more byte ranges that need to be uploaded.
 
@@ -230,25 +234,22 @@ Content-Type: application/json
 }
 ```
 
-## Remarks
+#### Remarks
 
 - The **nextExpectedRanges** property doesn't always list all of the missing ranges.
 - On successful fragment writes, it returns the next range to start from (for example, `523-`).
-- On failures where the client sent a fragment the server already received, the server responds with `HTTP 416 Requested Range Not Satisfiable`. To get a more detailed list of missing ranges, you can [request upload status](#resuming-an-in-progress-upload).
+- On failures where the client sent a fragment the server already received, the server responds with `HTTP 416 Requested Range Not Satisfiable`. To get a more detailed list of missing ranges, you can [request upload status](#example-6-resuming-an-in-progress-upload).
 - If you include the `Authorization` header when issuing the PUT call, it might result in an `HTTP 401 Unauthorized` response. Only include the `Authorization` header and bearer token when issuing the POST request during the first step. Don't include it when issuing the PUT call.
 
-## Completing a file
+### Example 3: Completing a file (deferCommit is false)
 
 If **deferCommit** is `false` or unset, then the upload is automatically completed when the final byte range of the file is PUT to the upload URL.
 
-If **deferCommit** is `true`, you can explicitly complete the upload in two ways:
-
-- After the final byte range of the file is PUT to the upload URL, send a final POST request to the upload URL with zero-length content (currently only supported on OneDrive for Business and SharePoint).
-- After the final byte range of the file is PUT to the upload URL, send a final PUT request in the same way that you would [handle upload errors](#handle-upload-errors) (currently only supported on OneDrive Personal).
-
 When the upload is completed, the server responds to the final request with an `HTTP 201 Created` or `HTTP 200 OK`.
 The response body also includes the default property set for the **driveItem** that represents the completed file.
 
+#### Request
+
 <!-- { "blockType": "ignored" } -->
 
 ```http
@@ -263,6 +264,8 @@ Content-Range: bytes 101-127/128
 >
 > - To upload large files using SDKs, see [Upload large files using the Microsoft Graph SDKs](/graph/sdks/large-file-upload).
 
+#### Response
+
 <!-- { "blockType": "ignored" } -->
 
 ```http
@@ -277,6 +280,18 @@ Content-Type: application/json
 }
 ```
 
+### Example 4: Completing a file (deferCommit is false)
+
+If **deferCommit** is `true`, you can explicitly complete the upload in two ways:
+
+- After the final byte range of the file is PUT to the upload URL, send a final POST request to the upload URL with zero-length content (currently only supported on OneDrive for Business and SharePoint).
+- After the final byte range of the file is PUT to the upload URL, send a final PUT request in the same way that you would [handle upload errors](#example-7-handle-upload-errors) (currently only supported on OneDrive Personal).
+
+When the upload is completed, the server responds to the final request with an `HTTP 201 Created` or `HTTP 200 OK`.
+The response body also includes the default property set for the **driveItem** that represents the completed file.
+
+#### Request
+
 <!-- { "blockType": "ignored"} -->
 
 ```http
@@ -290,6 +305,8 @@ Content-Length: 0
 
 <!-- { "blockType": "ignored"} -->
 
+#### Response
+
 ```http
 HTTP/1.1 201 Created
 Content-Type: application/json
@@ -302,24 +319,7 @@ Content-Type: application/json
 }
 ```
 
-## Handling upload conflicts
-
-If a conflict occurs after the file is uploaded (for example, an item with the same name was created during the upload session), an error is returned when the last byte range is uploaded.
-
-```http
-HTTP/1.1 409 Conflict
-Content-Type: application/json
-
-{
-  "error":
-  {
-    "code": "nameAlreadyExists",
-    "message": "Another file exists with the same name as the uploaded session. You can redirect the upload session to use a new filename by calling PUT with the new metadata and @microsoft.graph.sourceUrl attribute.",
-  }
-}
-```
-
-## Cancel the upload session
+### Example 5: Cancel the upload session
 
 To cancel an upload session, send a DELETE request to the upload URL.
 This cleans up the temporary file holding the data previously uploaded.
@@ -328,7 +328,7 @@ This should be used in scenarios where the upload is aborted, for example, if th
 Temporary files and their accompanying upload session are automatically cleaned up after the **expirationDateTime** has passed.
 Temporary files might not be deleted immediately after the expiration time has elapsed.
 
-### Request
+#### Request
 
 <!-- { "blockType": "ignored" } -->
 
@@ -340,7 +340,7 @@ DELETE https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
 >
 > - To upload large files using SDKs, see [Upload large files using the Microsoft Graph SDKs](/graph/sdks/large-file-upload).
 
-### Response
+#### Response
 
 The following example shows the response.
 
@@ -350,15 +350,15 @@ The following example shows the response.
 HTTP/1.1 204 No Content
 ```
 
-## Resuming an in-progress upload
+### Example 6: Resuming an in-progress upload
 
 If an upload request is disconnected or fails before the request is completed, all bytes in that request are ignored.
 This can occur if the connection between your app and the service is dropped.
 If this occurs, your app can still resume the file transfer from the previously completed fragment.
 
 To find out which byte ranges have been received previously, your app can request the status of an upload session.
 
-### Example
+#### Request
 
 Query the status of the upload by sending a GET request to the `uploadUrl`.
 
@@ -374,6 +374,7 @@ The server responds with a list of missing byte ranges that need to be uploaded
 >
 > - To upload large files using SDKs, see [Upload large files using the Microsoft Graph SDKs](/graph/sdks/large-file-upload).
 
+#### Response
 
 <!-- { "blockType": "ignored" } -->
 
@@ -387,11 +388,9 @@ Content-Type: application/json
 }
 ```
 
-### Upload remaining data
-
-Now that your app knows where to start the upload from, resume the upload by following the steps in [upload bytes to the upload session](#upload-bytes-to-the-upload-session).
+Now that your app knows where to start the upload from, resume the upload by following the steps in [upload bytes to the upload session](#example-2-upload-bytes-to-the-upload-session).
 
-## Handle upload errors
+### Example 7: Handle upload errors
 
 When the last byte range of a file is uploaded, it's possible for an error to occur.
 This can be due to a name conflict or quota limitation being exceeded.
@@ -402,6 +401,8 @@ This new request should correct the source of error that generated the original
 
 To indicate that your app is committing an existing upload session, the PUT request must include the `@microsoft.graph.sourceUrl` property with the value of your upload session URL.
 
+#### Request
+
 <!-- { "blockType": "request", "name": "explicit-upload-commit"} -->
 
 ```http
@@ -418,7 +419,7 @@ If-Match: {etag or ctag}
 
 >**Note:** You can use the `@microsoft.graph.conflictBehavior` and `if-match` headers as expected in this call.
 
-### Response
+#### Response
 
 If the file can be committed using the new metadata, an `HTTP 201 Created` or `HTTP 200 OK` response is returned with the Item metadata for the uploaded file.
 
@@ -452,6 +453,21 @@ Content-Type: application/json
 
 ## Error responses
 
+If a conflict occurs after the file is uploaded (for example, an item with the same name was created during the upload session), an error is returned when the last byte range is uploaded.
+
+```http
+HTTP/1.1 409 Conflict
+Content-Type: application/json
+
+{
+  "error":
+  {
+    "code": "nameAlreadyExists",
+    "message": "Another file exists with the same name as the uploaded session. You can redirect the upload session to use a new filename by calling PUT with the new metadata and @microsoft.graph.sourceUrl attribute.",
+  }
+}
+```
+
 See the [Error Responses][error-response] article for details about
 how errors are returned.