Microsoft Graph Excel API

REST API for accessing and manipulating Excel workbooks stored in OneDrive for Business, SharePoint sites, or Group drives through Microsoft Graph. Supports worksheet, table, chart, range, named item, and function operations.

Documentation

Specifications

SDKs

Examples

Schemas & Data

Other Resources

OpenAPI Specification

microsoft-excel-graph-api.yaml Raw ↑
openapi: 3.0.3
info:
  title: Microsoft Graph Excel API
  description: >-
    REST API for accessing and manipulating Excel workbooks stored in OneDrive
    for Business, SharePoint sites, or Group drives through Microsoft Graph.
  version: 1.0.0
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/graph/support
  license:
    name: Microsoft API Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/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:
      - Files.Read
      - Files.ReadWrite
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization using 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
  schemas:
    WorkbookSessionInfo:
      type: object
      description: Session information for a workbook session.
      properties:
        id:
          type: string
          description: The session identifier.
          example: '{session-id}'
        persistChanges:
          type: boolean
          description: Whether changes are persisted.
          example: true
    Worksheet:
      type: object
      description: Represents an Excel worksheet.
      properties:
        id:
          type: string
          description: Unique identifier for the worksheet.
          example: '{00000000-0001-0000-0000-000000000000}'
        name:
          type: string
          description: The display name of the worksheet.
          example: Sheet1
        position:
          type: integer
          description: The zero-based position of the worksheet.
          example: 0
        visibility:
          type: string
          description: Worksheet visibility.
          enum:
            - Visible
            - Hidden
            - VeryHidden
          example: Visible
    WorksheetCollection:
      type: object
      description: Collection of worksheets.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Worksheet'
    Table:
      type: object
      description: Represents an Excel table.
      properties:
        id:
          type: string
          description: Unique identifier for the table.
          example: '2'
        name:
          type: string
          description: The name of the table.
          example: SalesData
        showHeaders:
          type: boolean
          description: Whether the header row is visible.
          example: true
        showTotals:
          type: boolean
          description: Whether the total row is visible.
          example: false
        style:
          type: string
          description: Table style name.
          example: TableStyleMedium4
    TableCollection:
      type: object
      description: Collection of tables.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Table'
    TableRow:
      type: object
      description: Represents a row in an Excel table.
      properties:
        index:
          type: integer
          description: Zero-based index of the row.
          example: 0
        values:
          type: array
          description: Raw values of the row.
          items:
            type: array
            items: {}
    TableRowCollection:
      type: object
      description: Collection of table rows.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/TableRow'
    TableColumn:
      type: object
      description: Represents a column in an Excel table.
      properties:
        id:
          type: string
          description: Unique identifier for the column.
          example: '1'
        index:
          type: integer
          description: Zero-based index of the column.
          example: 0
        name:
          type: string
          description: The name of the column.
          example: Date
        values:
          type: array
          description: Raw values of the column.
          items:
            type: array
            items: {}
    TableColumnCollection:
      type: object
      description: Collection of table columns.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/TableColumn'
    Chart:
      type: object
      description: Represents an Excel chart object.
      properties:
        id:
          type: string
          description: Unique identifier for the chart.
          example: '{00000000-0008-0000-0100-000003000000}'
        name:
          type: string
          description: The name of the chart.
          example: Chart 1
        height:
          type: number
          format: double
          description: Height in points.
          example: 235.5
        width:
          type: number
          format: double
          description: Width in points.
          example: 401.25
        left:
          type: number
          format: double
          description: Left position in points.
          example: 276.0
        top:
          type: number
          format: double
          description: Top position in points.
          example: 0.0
    ChartCollection:
      type: object
      description: Collection of charts.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Chart'
    Range:
      type: object
      description: Represents a cell range in a worksheet.
      properties:
        address:
          type: string
          description: Range reference in A1-style notation.
          example: 'Sheet1!A1:B2'
        addressLocal:
          type: string
          description: Range reference in locale-specific notation.
          example: 'Sheet1!A1:B2'
        cellCount:
          type: integer
          description: Number of cells in the range.
          example: 4
        columnCount:
          type: integer
          description: Number of columns.
          example: 2
        columnIndex:
          type: integer
          description: Column number of the first cell.
          example: 0
        rowCount:
          type: integer
          description: Number of rows.
          example: 2
        rowIndex:
          type: integer
          description: Row number of the first cell.
          example: 0
        hidden:
          type: boolean
          description: Whether the range is hidden.
          example: false
        formulas:
          type: array
          description: Formulas in A1-style notation.
          items:
            type: array
            items: {}
        values:
          type: array
          description: Raw values of the range.
          items:
            type: array
            items: {}
        text:
          type: array
          description: Text values of the range.
          items:
            type: array
            items: {}
        numberFormat:
          type: array
          description: Number format codes.
          items:
            type: array
            items:
              type: string
        valueTypes:
          type: array
          description: Type of data in each cell.
          items:
            type: array
            items:
              type: string
    NamedItem:
      type: object
      description: Represents a defined name for a cell range or value.
      properties:
        name:
          type: string
          description: The name of the named item.
          example: data
        type:
          type: string
          description: The type of the named item.
          example: Range
        value:
          type: string
          description: The formula or range reference.
          example: 'Range!$A$1:$D$3'
        visible:
          type: boolean
          description: Whether the named item is visible.
          example: true
    NamedItemCollection:
      type: object
      description: Collection of named items.
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/NamedItem'
    WorkbookFunctionResult:
      type: object
      description: Result of a workbook function call.
      properties:
        error:
          type: string
          nullable: true
          description: Error information if the function failed.
        value: {}
    ErrorResponse:
      type: object
      description: Error response from the API.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code.
              example: ItemAlreadyExists
            message:
              type: string
              description: Error message.
              example: A resource with the same name or identifier already exists.
            innerError:
              type: object
              properties:
                request-id:
                  type: string
                date:
                  type: string
                  format: date-time
tags:
  - name: Sessions
    description: Workbook session management operations.
  - name: Worksheets
    description: Operations for managing worksheets within a workbook.
  - name: Tables
    description: Operations for managing tables within worksheets.
  - name: Table Rows
    description: Operations for managing table row data.
  - name: Table Columns
    description: Operations for managing table columns.
  - name: Charts
    description: Operations for managing charts within worksheets.
  - name: Ranges
    description: Operations for reading and writing cell ranges.
  - name: Named Items
    description: Operations for managing named ranges and values.
  - name: Functions
    description: Workbook function operations.
paths:
  /me/drive/items/{item-id}/workbook/createSession:
    post:
      operationId: createWorkbookSession
      summary: Microsoft Excel Create Workbook Session
      description: Create a new workbook session with optional persistence.
      tags:
        - Sessions
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file in OneDrive.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                persistChanges:
                  type: boolean
                  description: Whether to persist changes to the workbook.
            examples:
              CreateWorkbookSessionRequestExample:
                summary: Default createWorkbookSession request
                x-microcks-default: true
                value:
                  persistChanges: true
      responses:
        '201':
          description: Session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkbookSessionInfo'
              examples:
                CreateWorkbookSession201Example:
                  summary: Default createWorkbookSession 201 response
                  x-microcks-default: true
                  value:
                    id: '{session-id}'
                    persistChanges: true
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/worksheets:
    get:
      operationId: listWorksheets
      summary: Microsoft Excel List Worksheets
      description: Retrieve a list of worksheets in the workbook.
      tags:
        - Worksheets
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID for performance.
          schema:
            type: string
      responses:
        '200':
          description: Worksheets returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorksheetCollection'
              examples:
                ListWorksheets200Example:
                  summary: Default listWorksheets 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: '{00000000-0001-0000-0000-000000000000}'
                        name: Sheet1
                        position: 0
                        visibility: Visible
        '401':
          description: Unauthorized.
        '404':
          description: Workbook not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createWorksheet
      summary: Microsoft Excel Create Worksheet
      description: Add a new worksheet to the workbook.
      tags:
        - Worksheets
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the new worksheet.
            examples:
              CreateWorksheetRequestExample:
                summary: Default createWorksheet request
                x-microcks-default: true
                value:
                  name: NewSheet
      responses:
        '201':
          description: Worksheet created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worksheet'
              examples:
                CreateWorksheet201Example:
                  summary: Default createWorksheet 201 response
                  x-microcks-default: true
                  value:
                    id: '{75A18F35-34AA-4F44-97CC-FDC3C05D9F40}'
                    name: NewSheet
                    position: 5
                    visibility: Visible
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/worksheets/{worksheet-id-or-name}:
    get:
      operationId: getWorksheet
      summary: Microsoft Excel Get Worksheet
      description: Retrieve a specific worksheet by ID or name.
      tags:
        - Worksheets
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: worksheet-id-or-name
          in: path
          required: true
          description: Worksheet ID or name.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      responses:
        '200':
          description: Worksheet returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worksheet'
              examples:
                GetWorksheet200Example:
                  summary: Default getWorksheet 200 response
                  x-microcks-default: true
                  value:
                    id: '{00000000-0001-0000-0000-000000000000}'
                    name: Sheet1
                    position: 0
                    visibility: Visible
        '401':
          description: Unauthorized.
        '404':
          description: Worksheet not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateWorksheet
      summary: Microsoft Excel Update Worksheet
      description: Update worksheet properties such as name or position.
      tags:
        - Worksheets
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: worksheet-id-or-name
          in: path
          required: true
          description: Worksheet ID or name.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Worksheet'
            examples:
              UpdateWorksheetRequestExample:
                summary: Default updateWorksheet request
                x-microcks-default: true
                value:
                  name: RenamedSheet
                  position: 3
      responses:
        '200':
          description: Worksheet updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worksheet'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '404':
          description: Worksheet not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteWorksheet
      summary: Microsoft Excel Delete Worksheet
      description: Delete a worksheet from the workbook.
      tags:
        - Worksheets
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: worksheet-id-or-name
          in: path
          required: true
          description: Worksheet ID or name.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      responses:
        '204':
          description: Worksheet deleted successfully.
        '401':
          description: Unauthorized.
        '404':
          description: Worksheet not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/worksheets/{worksheet-id-or-name}/tables:
    get:
      operationId: listTables
      summary: Microsoft Excel List Tables
      description: Retrieve a list of tables in the worksheet.
      tags:
        - Tables
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: worksheet-id-or-name
          in: path
          required: true
          description: Worksheet ID or name.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      responses:
        '200':
          description: Tables returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableCollection'
              examples:
                ListTables200Example:
                  summary: Default listTables 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: '1'
                        name: SalesData
                        showHeaders: true
                        showTotals: false
                        style: TableStyleMedium4
        '401':
          description: Unauthorized.
        '404':
          description: Worksheet not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/tables/{table-id}:
    patch:
      operationId: updateTable
      summary: Microsoft Excel Update Table
      description: Update table properties such as name or style.
      tags:
        - Tables
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: table-id
          in: path
          required: true
          description: The ID or name of the table.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Table'
            examples:
              UpdateTableRequestExample:
                summary: Default updateTable request
                x-microcks-default: true
                value:
                  name: UpdatedTable
                  showHeaders: true
                  showTotals: false
                  style: TableStyleMedium4
      responses:
        '200':
          description: Table updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '404':
          description: Table not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/tables/{table-id}/rows:
    get:
      operationId: listTableRows
      summary: Microsoft Excel List Table Rows
      description: Retrieve a list of rows in the table.
      tags:
        - Table Rows
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: table-id
          in: path
          required: true
          description: The ID or name of the table.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      responses:
        '200':
          description: Table rows returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableRowCollection'
              examples:
                ListTableRows200Example:
                  summary: Default listTableRows 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - index: 0
                        values:
                          - - 42019
                            - 53
                            - 34
        '401':
          description: Unauthorized.
        '404':
          description: Table not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addTableRow
      summary: Microsoft Excel Add Table Row
      description: Add a new row to the table.
      tags:
        - Table Rows
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: table-id
          in: path
          required: true
          description: The ID or name of the table.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                values:
                  type: array
                  items:
                    type: array
                    items: {}
                index:
                  type: integer
                  nullable: true
            examples:
              AddTableRowRequestExample:
                summary: Default addTableRow request
                x-microcks-default: true
                value:
                  values:
                    - - 'Jan-15-2026'
                      - '49'
                      - '37'
                  index: null
      responses:
        '201':
          description: Row added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableRow'
              examples:
                AddTableRow201Example:
                  summary: Default addTableRow 201 response
                  x-microcks-default: true
                  value:
                    index: 6
                    values:
                      - - 'Jan-15-2026'
                        - 49
                        - 37
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/tables/{table-id}/rows/$/itemAt(index={row-index}):
    delete:
      operationId: deleteTableRow
      summary: Microsoft Excel Delete Table Row
      description: Delete a row from the table by index.
      tags:
        - Table Rows
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: table-id
          in: path
          required: true
          description: The ID or name of the table.
          schema:
            type: string
        - name: row-index
          in: path
          required: true
          description: Zero-based index of the row to delete.
          schema:
            type: integer
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      responses:
        '204':
          description: Row deleted successfully.
        '401':
          description: Unauthorized.
        '404':
          description: Row not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/tables/{table-id}/columns:
    get:
      operationId: listTableColumns
      summary: Microsoft Excel List Table Columns
      description: Retrieve a list of columns in the table.
      tags:
        - Table Columns
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: table-id
          in: path
          required: true
          description: The ID or name of the table.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      responses:
        '200':
          description: Columns returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableColumnCollection'
              examples:
                ListTableColumns200Example:
                  summary: Default listTableColumns 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: '1'
                        index: 0
                        name: Date
                        values:
                          - - Date
                          - - 42019
        '401':
          description: Unauthorized.
        '404':
          description: Table not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addTableColumn
      summary: Microsoft Excel Add Table Column
      description: Add a new column to the table.
      tags:
        - Table Columns
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: table-id
          in: path
          required: true
          description: The ID or name of the table.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                values:
                  type: array
                  items:
                    type: array
                    items: {}
                index:
                  type: integer
            examples:
              AddTableColumnRequestExample:
                summary: Default addTableColumn request
                x-microcks-default: true
                value:
                  values:
                    - - Status
                    - - Open
                    - - Closed
                  index: 2
      responses:
        '201':
          description: Column added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableColumn'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/tables/{table-id}/columns/{column-id}:
    delete:
      operationId: deleteTableColumn
      summary: Microsoft Excel Delete Table Column
      description: Delete a column from the table.
      tags:
        - Table Columns
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: table-id
          in: path
          required: true
          description: The ID or name of the table.
          schema:
            type: string
        - name: column-id
          in: path
          required: true
          description: The ID of the column to delete.
          schema:
            type: string
        - name: workbook-session-id
          in: header
          required: false
          description: Workbook session ID.
          schema:
            type: string
      responses:
        '204':
          description: Column deleted successfully.
        '401':
          description: Unauthorized.
        '404':
          description: Column not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{item-id}/workbook/tables/{table-id}/convertToRange:
    post:
      operationId: convertTableToRange
      summary: Microsoft Excel Convert Table to Range
      description: Convert the table to a regular range of cells.
      tags:
        - Tables
      parameters:
        - name: item-id
          in: path
          required: true
          description: The ID of the workbook file.
          schema:
            type: string
        - name: table-id
          in: path
          required: true
          description: The ID or name of the table.
          schema:
            type:

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-excel/refs/heads/main/openapi/microsoft-excel-graph-api.yaml