---
title: "Prepare an upload to OneDrive or SharePoint, or a replacement of an existing file's content, for a client with a shell"
method: POST
path: "/v1/capabilities/microsoft-365/drive-upload-sessions"
tags: ["Capability Sources"]
---

# Prepare an upload to OneDrive or SharePoint, or a replacement of an existing file's content, for a client with a shell

`POST /v1/capabilities/microsoft-365/drive-upload-sessions`

## Request

- Base URL: `https://api.openworklabs.com`
- URL: `https://api.openworklabs.com/v1/capabilities/microsoft-365/drive-upload-sessions`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Prepare a Microsoft upload session for an explicitly requested upload. This does not upload bytes or prove completion. With itemId and baseRevision the upload replaces that file's content as a new version; otherwise it creates name in folderId (or the top of the drive). Do not automatically create another session after an uncertain result. Uses the selected connection.

## Request body

- object
  - `driveId` string: The file's driveId from a search, folder or link result. Omit for the member's own OneDrive.
  - `itemId` string: Replace this existing file's content. It keeps its link and sharing; the previous version stays in its version history.
  - `baseRevision` string: Required with itemId: the eTag your copy was downloaded from. Refused with drive_conflict when the file changed since; download it again and reapply the edits, or save a new file.
  - `folderId` string: New files only: the folder to create the file in; omit for the top of the drive.
  - `name` string: New files only: the file name.
  - `conflictBehavior` 'fail' | 'rename': New files only: fail, or let Microsoft rename the file when the name is taken.
  - `size` integer, required: Exact file size in bytes.

## Response `200`

Secret upload session; file not yet uploaded.

- Microsoft365DriveUploadSessionResponse
  - `ok` true, required
  - `uploadUrl` string, uri, required: Secret bearer upload-session URL. Never print, share, persist or log it, and never send an Authorization header to it.
  - `method` 'PUT', required
  - `size` integer, required
  - `chunkSize` 10485760, required
  - `expiresAt` string, date-time, nullable, required
  - `replaces` object: Present when the upload replaces an existing file's content.
    - `itemId` string, required
    - `driveId` string, required
    - `previousRevision` string, nullable, required
  - `instructions` string, required

## Other responses

- `400`: Invalid request, a folder, or an item without content.
- `401`: Sign in first.
- `403`: Organization policy blocks the selected connection.
- `409`: Connect Microsoft 365 with the needed permission, or the file changed since baseRevision (drive_conflict).
- `502`: Microsoft refused or did not return the file; the message gives Microsoft's reason.

## Changes

- **2026-10-23** `c93387179b31`: 3 breaking, 5 info
  - the response property `anyOf[subschema #2]/currentRevision` became nullable for the status `409`
  - the response property `anyOf[subschema #2]/modifiedTime` became nullable for the status `409`
  - the response property `replaces/previousRevision` became nullable for the status `200`
  - response property `anyOf[#/components/schemas/InvalidRequestError]/details/items/path/items/` list-of-types was narrowed by removing types `number` from media type `application/json` of response `400`
  - …4 more
- **2026-10-23** `3e38eb291e52`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openworklabs/apis/den-api/changes/v1/capabilities/microsoft-365/drive-upload-sessions/post.md)

---

[API](https://skmtc.dev/openworklabs/apis/den-api.md) - [All operations](https://skmtc.dev/openworklabs/apis/den-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openworklabs/apis/den-api/revisions/8170cf4a92ca?raw)