Microsoft Graph Excel API

openapi: 3.0.3
info:
  title: Microsoft Graph Excel API
  description: >-
    The Microsoft Graph Excel API provides REST access to Excel workbooks stored in OneDrive,
    SharePoint, or Teams. Supports reading and writing cell values, executing formulas, managing
    worksheets, creating charts and tables, and running workbook sessions for transactional
    batch operations on Excel files.
  version: "v1.0"
  contact:
    name: Microsoft Graph Support
    url: https://learn.microsoft.com/en-us/graph/overview
  termsOfService: https://www.microsoft.com/en-us/servicesagreement
  license:
    name: Microsoft APIs Terms of Use
    url: https://www.microsoft.com/en-us/servicesagreement
servers:
  - url: https://graph.microsoft.com/v1.0
    description: Microsoft Graph API Production
tags:
  - name: Workbooks
    description: Excel workbook access and session management
  - name: Worksheets
    description: Worksheet management within a workbook
  - name: Ranges
    description: Cell range read/write operations
  - name: Tables
    description: Excel table management
  - name: Charts
    description: Chart creation and management
security:
  - oauth2: []
paths:
  /me/drive/items/{driveItemId}/workbook/worksheets:
    get:
      operationId: listWorksheets
      summary: Microsoft Excel List Worksheets
      description: "Retrieve a list of worksheets in an Excel workbook stored in OneDrive."
      tags:
        - Worksheets
      parameters:
        - name: driveItemId
          in: path
          required: true
          description: "OneDrive item ID of the Excel workbook."
          schema:
            type: string
      responses:
        '200':
          description: "List of worksheets."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorksheetList'
              examples:
                listWorksheets200Example:
                  summary: Default listWorksheets 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: "sheet1"
                        name: "Sheet1"
                        position: 0
                        visibility: "Visible"
        '401':
          description: "Unauthorized."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                listWorksheets401Example:
                  summary: Default listWorksheets 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: "Unauthorized"
                      message: "Access token is missing or invalid"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addWorksheet
      summary: Microsoft Excel Add Worksheet
      description: "Add a new worksheet to an Excel workbook."
      tags:
        - Worksheets
      parameters:
        - name: driveItemId
          in: path
          required: true
          description: "OneDrive item ID of the Excel workbook."
          schema:
            type: string
      requestBody:
        required: true
        description: "Worksheet creation parameters."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorksheetInput'
            examples:
              addWorksheetRequestExample:
                summary: Default addWorksheet request
                x-microcks-default: true
                value:
                  name: "Sales Data"
      responses:
        '201':
          description: "Worksheet created."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worksheet'
              examples:
                addWorksheet201Example:
                  summary: Default addWorksheet 201 response
                  x-microcks-default: true
                  value:
                    id: "sheet2"
                    name: "Sales Data"
                    position: 1
                    visibility: "Visible"
        '401':
          description: "Unauthorized."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                addWorksheet401Example:
                  summary: Default addWorksheet 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: "Unauthorized"
                      message: "Access token is missing or invalid"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{driveItemId}/workbook/worksheets/{worksheetId}/range(address='{address}'):
    get:
      operationId: getRange
      summary: Microsoft Excel Get Cell Range Values
      description: "Retrieve cell values, formulas, and formatting for a specified range in a worksheet."
      tags:
        - Ranges
      parameters:
        - name: driveItemId
          in: path
          required: true
          description: "OneDrive item ID of the Excel workbook."
          schema:
            type: string
        - name: worksheetId
          in: path
          required: true
          description: "Worksheet ID or name."
          schema:
            type: string
        - name: address
          in: path
          required: true
          description: "Cell range address (e.g., A1:D10)."
          schema:
            type: string
      responses:
        '200':
          description: "Range data including values, formulas, and format."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Range'
              examples:
                getRange200Example:
                  summary: Default getRange 200 response
                  x-microcks-default: true
                  value:
                    address: "Sheet1!A1:B2"
                    values:
                      - ["Name", "Value"]
                      - ["Revenue", 50000]
                    formulas:
                      - ["Name", "Value"]
                      - ["Revenue", "50000"]
        '401':
          description: "Unauthorized."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                getRange401Example:
                  summary: Default getRange 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: "Unauthorized"
                      message: "Access token is missing or invalid"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateRange
      summary: Microsoft Excel Update Cell Range Values
      description: "Write values or formulas to a specified cell range in a worksheet."
      tags:
        - Ranges
      parameters:
        - name: driveItemId
          in: path
          required: true
          description: "OneDrive item ID of the Excel workbook."
          schema:
            type: string
        - name: worksheetId
          in: path
          required: true
          description: "Worksheet ID or name."
          schema:
            type: string
        - name: address
          in: path
          required: true
          description: "Cell range address (e.g., A1:D10)."
          schema:
            type: string
      requestBody:
        required: true
        description: "Range values to write."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RangeInput'
            examples:
              updateRangeRequestExample:
                summary: Default updateRange request
                x-microcks-default: true
                value:
                  values:
                    - ["Name", "Value"]
                    - ["Revenue", 50000]
      responses:
        '200':
          description: "Updated range."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Range'
              examples:
                updateRange200Example:
                  summary: Default updateRange 200 response
                  x-microcks-default: true
                  value:
                    address: "Sheet1!A1:B2"
                    values:
                      - ["Name", "Value"]
                      - ["Revenue", 50000]
        '401':
          description: "Unauthorized."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                updateRange401Example:
                  summary: Default updateRange 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: "Unauthorized"
                      message: "Access token is missing or invalid"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{driveItemId}/workbook/worksheets/{worksheetId}/tables:
    get:
      operationId: listTables
      summary: Microsoft Excel List Worksheet Tables
      description: "List all tables defined in an Excel worksheet."
      tags:
        - Tables
      parameters:
        - name: driveItemId
          in: path
          required: true
          description: "OneDrive item ID of the Excel workbook."
          schema:
            type: string
        - name: worksheetId
          in: path
          required: true
          description: "Worksheet ID or name."
          schema:
            type: string
      responses:
        '200':
          description: "List of tables."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableList'
              examples:
                listTables200Example:
                  summary: Default listTables 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: "table1"
                        name: "SalesTable"
                        showHeaders: true
                        showTotals: false
        '401':
          description: "Unauthorized."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                listTables401Example:
                  summary: Default listTables 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: "Unauthorized"
                      message: "Access token is missing or invalid"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{driveItemId}/workbook/worksheets/{worksheetId}/charts:
    get:
      operationId: listCharts
      summary: Microsoft Excel List Worksheet Charts
      description: "List all charts in an Excel worksheet."
      tags:
        - Charts
      parameters:
        - name: driveItemId
          in: path
          required: true
          description: "OneDrive item ID of the Excel workbook."
          schema:
            type: string
        - name: worksheetId
          in: path
          required: true
          description: "Worksheet ID or name."
          schema:
            type: string
      responses:
        '200':
          description: "List of charts."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartList'
              examples:
                listCharts200Example:
                  summary: Default listCharts 200 response
                  x-microcks-default: true
                  value:
                    value:
                      - id: "chart1"
                        name: "SalesChart"
                        chartType: "ColumnClustered"
                        height: 300
                        width: 500
        '401':
          description: "Unauthorized."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                listCharts401Example:
                  summary: Default listCharts 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: "Unauthorized"
                      message: "Access token is missing or invalid"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addChart
      summary: Microsoft Excel Add Chart to Worksheet
      description: "Create a new chart in an Excel worksheet from a specified data range."
      tags:
        - Charts
      parameters:
        - name: driveItemId
          in: path
          required: true
          description: "OneDrive item ID of the Excel workbook."
          schema:
            type: string
        - name: worksheetId
          in: path
          required: true
          description: "Worksheet ID or name."
          schema:
            type: string
      requestBody:
        required: true
        description: "Chart creation parameters."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChartInput'
            examples:
              addChartRequestExample:
                summary: Default addChart request
                x-microcks-default: true
                value:
                  type: "ColumnClustered"
                  sourceData: "Sheet1!A1:B10"
                  seriesBy: "Auto"
      responses:
        '201':
          description: "Chart created."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chart'
              examples:
                addChart201Example:
                  summary: Default addChart 201 response
                  x-microcks-default: true
                  value:
                    id: "chart2"
                    name: "Chart 1"
                    chartType: "ColumnClustered"
                    height: 300
                    width: 500
        '401':
          description: "Unauthorized."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                addChart401Example:
                  summary: Default addChart 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: "Unauthorized"
                      message: "Access token is missing or invalid"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/drive/items/{driveItemId}/workbook/createSession:
    post:
      operationId: createWorkbookSession
      summary: Microsoft Excel Create Workbook Session
      description: "Create a persistent workbook session for transactional batch operations on an Excel file."
      tags:
        - Workbooks
      parameters:
        - name: driveItemId
          in: path
          required: true
          description: "OneDrive item ID of the Excel workbook."
          schema:
            type: string
      requestBody:
        required: true
        description: "Session creation parameters."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionInput'
            examples:
              createWorkbookSessionRequestExample:
                summary: Default createWorkbookSession request
                x-microcks-default: true
                value:
                  persistChanges: true
      responses:
        '201':
          description: "Session created."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
              examples:
                createWorkbookSession201Example:
                  summary: Default createWorkbookSession 201 response
                  x-microcks-default: true
                  value:
                    id: "session-abc123"
                    persistChanges: true
        '401':
          description: "Unauthorized."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                createWorkbookSession401Example:
                  summary: Default createWorkbookSession 401 response
                  x-microcks-default: true
                  value:
                    error:
                      code: "Unauthorized"
                      message: "Access token is missing or invalid"
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Files.ReadWrite: "Read and write user files"
            Files.ReadWrite.All: "Read and write all files"
  schemas:
    Worksheet:
      type: object
      description: "An Excel worksheet."
      properties:
        id:
          type: string
          description: "Worksheet identifier."
          example: "sheet1"
        name:
          type: string
          description: "Worksheet display name."
          example: "Sheet1"
        position:
          type: integer
          description: "Zero-based index position of the worksheet."
          example: 0
        visibility:
          type: string
          description: "Worksheet visibility."
          enum: [Visible, Hidden, VeryHidden]
          example: "Visible"
    WorksheetInput:
      type: object
      description: "Request to add a new worksheet."
      properties:
        name:
          type: string
          description: "Name for the new worksheet."
          example: "Sales Data"
    WorksheetList:
      type: object
      description: "List of worksheets."
      properties:
        value:
          type: array
          description: "Array of worksheets."
          items:
            $ref: '#/components/schemas/Worksheet'
    Range:
      type: object
      description: "A cell range in a worksheet with values and formulas."
      properties:
        address:
          type: string
          description: "A1-style range address."
          example: "Sheet1!A1:B10"
        values:
          type: array
          description: "2D array of cell values."
          items:
            type: array
            items:
              type: string
        formulas:
          type: array
          description: "2D array of cell formulas."
          items:
            type: array
            items:
              type: string
    RangeInput:
      type: object
      description: "Request to write values to a range."
      properties:
        values:
          type: array
          description: "2D array of values to write."
          items:
            type: array
            items:
              type: string
    Table:
      type: object
      description: "An Excel table."
      properties:
        id:
          type: string
          description: "Table identifier."
          example: "table1"
        name:
          type: string
          description: "Table name."
          example: "SalesTable"
        showHeaders:
          type: boolean
          description: "Whether header row is shown."
          example: true
        showTotals:
          type: boolean
          description: "Whether total row is shown."
          example: false
    TableList:
      type: object
      description: "List of tables."
      properties:
        value:
          type: array
          description: "Array of tables."
          items:
            $ref: '#/components/schemas/Table'
    Chart:
      type: object
      description: "An Excel chart."
      properties:
        id:
          type: string
          description: "Chart identifier."
          example: "chart1"
        name:
          type: string
          description: "Chart name."
          example: "SalesChart"
        chartType:
          type: string
          description: "Chart type."
          example: "ColumnClustered"
        height:
          type: number
          description: "Chart height in points."
          example: 300
        width:
          type: number
          description: "Chart width in points."
          example: 500
    ChartInput:
      type: object
      description: "Request to create a chart."
      properties:
        type:
          type: string
          description: "Chart type."
          example: "ColumnClustered"
        sourceData:
          type: string
          description: "A1-style range address of the source data."
          example: "Sheet1!A1:B10"
        seriesBy:
          type: string
          description: "How series are plotted."
          enum: [Auto, Columns, Rows]
          example: "Auto"
    ChartList:
      type: object
      description: "List of charts."
      properties:
        value:
          type: array
          description: "Array of charts."
          items:
            $ref: '#/components/schemas/Chart'
    SessionInput:
      type: object
      description: "Request to create a workbook session."
      properties:
        persistChanges:
          type: boolean
          description: "Whether changes should be persisted to the workbook."
          example: true
    Session:
      type: object
      description: "A workbook session for batch operations."
      properties:
        id:
          type: string
          description: "Session identifier to pass in Workbook-Session-Id header."
          example: "session-abc123"
        persistChanges:
          type: boolean
          description: "Whether changes are persisted."
          example: true
    ErrorResponse:
      type: object
      description: "Microsoft Graph API error response."
      properties:
        error:
          type: object
          description: "Error details."
          properties:
            code:
              type: string
              description: "Error code."
              example: "Unauthorized"
            message:
              type: string
              description: "Error message."
              example: "Access token is missing or invalid."