Microsoft Word Drive Items API

openapi: 3.0.3
info:
  title: Microsoft Graph Word Body Drive Items API
  description: REST API for interacting with Word documents in Microsoft 365 and OneDrive via the Microsoft Graph unified endpoint. Provides operations for file management, content access, sharing, permissions, versioning, and document metadata for DriveItem resources.
  version: 1.0.0
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/graph/support
  license:
    name: Microsoft API License
    url: https://www.microsoft.com/en-us/legal/terms-of-use
  x-generated-from: documentation
  x-last-validated: '2026-04-18'
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint
security:
- oauth2: []
tags:
- name: Drive Items
  description: Operations for managing files and folders in OneDrive and SharePoint
paths:
  /me/drive/items/{item-id}:
    get:
      operationId: getDriveItem
      summary: Microsoft Word Get Drive Item
      description: Retrieve the metadata for a driveItem in a drive by file system path or ID.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      - name: $select
        in: query
        description: Select specific properties to return.
        schema:
          type: string
        example: id,name,size,file
      - name: $expand
        in: query
        description: Expand related entities inline.
        schema:
          type: string
        example: children
      responses:
        '200':
          description: Successfully retrieved the drive item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateDriveItem
      summary: Microsoft Word Update Drive Item
      description: Update the metadata for a driveItem by ID.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DriveItemUpdate'
      responses:
        '200':
          description: Successfully updated the drive item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteDriveItem
      summary: Microsoft Word Delete Drive Item
      description: Delete a driveItem by using its ID.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      responses:
        '204':
          description: Successfully deleted the drive item.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/children:
    get:
      operationId: listChildren
      summary: Microsoft Word List Children
      description: Return a collection of DriveItems in the children relationship of a DriveItem.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      - name: $top
        in: query
        description: The number of items to return in a result set.
        schema:
          type: integer
        example: 25
      - name: $orderby
        in: query
        description: Sort order for the result set.
        schema:
          type: string
        example: name asc
      - name: $select
        in: query
        description: Select specific properties to return.
        schema:
          type: string
      - name: $skipToken
        in: query
        description: Paging token for the next page of results.
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved children.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveItemCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createFolder
      summary: Microsoft Word Create Folder
      description: Create a new folder or DriveItem in a drive with a specified parent item or path.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFolderRequest'
      responses:
        '201':
          description: Successfully created the folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Conflict - item already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/copy:
    post:
      operationId: copyDriveItem
      summary: Microsoft Word Copy Drive Item
      description: Asynchronously create a copy of a driveItem, including any children, under a new parent item or with a new name.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyRequest'
      responses:
        '202':
          description: Accepted - copy operation is in progress.
          headers:
            Location:
              description: URL to monitor the copy operation progress.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/move:
    patch:
      operationId: moveDriveItem
      summary: Microsoft Word Move Drive Item
      description: Move a DriveItem to a new parent folder by updating the parentReference.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveRequest'
      responses:
        '200':
          description: Successfully moved the item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/preview:
    post:
      operationId: previewDriveItem
      summary: Microsoft Word Preview Drive Item
      description: Obtain short-lived embeddable URLs for an item to render a temporary preview.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  type: integer
                  description: Page number to start preview at.
                  example: 1
                zoom:
                  type: number
                  description: Zoom level to display preview at.
                  example: 1.0
      responses:
        '200':
          description: Successfully generated preview URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemPreviewInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/delta:
    get:
      operationId: trackChanges
      summary: Microsoft Word Track Changes
      description: Track changes to a driveItem and its children over time using delta queries.
      tags:
      - Drive Items
      parameters:
      - $ref: '#/components/parameters/itemId'
      - name: $token
        in: query
        description: Delta token for tracking changes since last query.
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved changes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveItemCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Forbidden:
      description: Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required or token expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ItemPreviewInfo:
      type: object
      description: Embeddable preview information for a drive item.
      properties:
        getUrl:
          type: string
          format: uri
          description: URL for embedding preview using HTTP GET.
          example: https://onedrive.live.com/embed?resid=abc123
        postParameters:
          type: string
          description: POST parameters for embedding preview.
        postUrl:
          type: string
          format: uri
          description: URL for embedding preview using HTTP POST.
    ErrorResponse:
      type: object
      description: Error response from the API.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code.
              example: itemNotFound
            message:
              type: string
              description: Human-readable error message.
              example: The resource could not be found.
            innerError:
              type: object
              properties:
                request-id:
                  type: string
                  description: Request correlation ID.
                  example: b0c6a5b0-4c0a-4c8e-9b0a-1234567890ab
                date:
                  type: string
                  format: date-time
                  description: Timestamp of the error.
                  example: '2025-03-21T20:01:37Z'
    FolderFacet:
      type: object
      description: Folder metadata facet for a driveItem.
      properties:
        childCount:
          type: integer
          description: Number of children in the folder.
          example: 120
    SharedFacet:
      type: object
      description: Indicates the item has been shared with others.
      properties:
        owner:
          $ref: '#/components/schemas/IdentitySet'
        scope:
          type: string
          description: Scope of sharing.
          example: users
    DriveItem:
      type: object
      description: Represents a file, folder, or other item stored in a drive.
      properties:
        id:
          type: string
          description: The unique identifier of the item within the drive.
          example: 01NKDM7HMOJTVYMDOSXFDK2QJDXCDI3WUK
        name:
          type: string
          description: The name of the item (filename and extension).
          example: quarterly-report.docx
        description:
          type: string
          description: A user-visible description of the item.
          example: Q4 2025 financial report
        size:
          type: integer
          format: int64
          description: Size of the item in bytes.
          example: 157286400
        webUrl:
          type: string
          format: uri
          description: URL that displays the resource in the browser.
          example: https://contoso-my.sharepoint.com/personal/user/Documents/report.docx
        webDavUrl:
          type: string
          format: uri
          description: WebDAV compatible URL for the item.
          example: https://contoso-my.sharepoint.com/personal/user/Documents/report.docx
        createdDateTime:
          type: string
          format: date-time
          description: Date and time of item creation.
          example: '2025-03-21T20:01:37Z'
        lastModifiedDateTime:
          type: string
          format: date-time
          description: Date and time the item was last modified.
          example: '2025-06-15T14:30:00Z'
        eTag:
          type: string
          description: ETag for the entire item (metadata + content).
          example: '"{86EB4C8E-D20D-46B9-AD41-23B8868DDA8A},1"'
        cTag:
          type: string
          description: ETag for the content of the item.
          example: '"{86EB4C8E-D20D-46B9-AD41-23B8868DDA8A},0"'
        createdBy:
          $ref: '#/components/schemas/IdentitySet'
        lastModifiedBy:
          $ref: '#/components/schemas/IdentitySet'
        parentReference:
          $ref: '#/components/schemas/ItemReference'
        file:
          $ref: '#/components/schemas/FileFacet'
        folder:
          $ref: '#/components/schemas/FolderFacet'
        shared:
          $ref: '#/components/schemas/SharedFacet'
    ItemReference:
      type: object
      description: Reference to a drive item's parent.
      properties:
        driveId:
          type: string
          description: Identifier of the drive containing the item.
          example: b!-RIj2DuyvEyV1T4NlOaMHk8XkS_I8MdFlUCq1BlcjgmhRfAj3-Z8RY2VpuvV_tpd
        id:
          type: string
          description: Identifier of the item in the drive.
          example: 01NKDM7HMOJTVYMDOSXFDK2QJDXCDI3WUK
        path:
          type: string
          description: Path from the root to the item.
          example: /drive/root:/Documents
    DriveItemUpdate:
      type: object
      description: Properties to update on a drive item.
      properties:
        name:
          type: string
          description: New name for the item.
          example: updated-report.docx
        description:
          type: string
          description: Updated description for the item.
          example: Updated quarterly report
        parentReference:
          $ref: '#/components/schemas/ItemReference'
    CreateFolderRequest:
      type: object
      description: Request body for creating a new folder.
      required:
      - name
      - folder
      properties:
        name:
          type: string
          description: Name of the new folder.
          example: New Folder
        folder:
          type: object
          description: Empty folder facet to indicate this is a folder.
        '@microsoft.graph.conflictBehavior':
          type: string
          description: Conflict resolution behavior (fail, replace, rename).
          example: rename
    FileFacet:
      type: object
      description: File metadata facet for a driveItem.
      properties:
        mimeType:
          type: string
          description: MIME type of the file.
          example: application/vnd.openxmlformats-officedocument.wordprocessingml.document
        hashes:
          type: object
          properties:
            sha1Hash:
              type: string
              description: SHA1 hash of the file content.
              example: aabbccdd1122334455
            quickXorHash:
              type: string
              description: QuickXor hash of the file content.
              example: aabbccdd1122334455
    DriveItemCollection:
      type: object
      description: Collection of drive items.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/DriveItem'
          description: Array of drive items.
        '@odata.nextLink':
          type: string
          description: URL to get the next page of results.
          example: https://graph.microsoft.com/v1.0/me/drive/items/123/children?$skiptoken=abc
    CopyRequest:
      type: object
      description: Request body for copying a drive item.
      properties:
        name:
          type: string
          description: New name for the copy.
          example: report-copy.docx
        parentReference:
          $ref: '#/components/schemas/ItemReference'
    MoveRequest:
      type: object
      description: Request body for moving a drive item.
      properties:
        name:
          type: string
          description: New name for the item after moving.
          example: report-moved.docx
        parentReference:
          $ref: '#/components/schemas/ItemReference'
    IdentitySet:
      type: object
      description: Keyed collection of identity resources.
      properties:
        user:
          type: object
          properties:
            id:
              type: string
              description: Unique identifier for the user.
              example: efee1b77-fb3b-4f65-99d6-274c11914d12
            displayName:
              type: string
              description: Display name of the user.
              example: Jane Smith
  parameters:
    itemId:
      name: item-id
      in: path
      required: true
      description: The unique identifier of the drive item.
      schema:
        type: string
      example: 01NKDM7HMOJTVYMDOSXFDK2QJDXCDI3WUK
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code flow with Microsoft Identity Platform.
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Files.Read: Read user files
            Files.ReadWrite: Read and write user files
            Files.Read.All: Read all files the user can access
            Files.ReadWrite.All: Read and write all files the user can access