cotera
Logo

Microsoft Excel 365

Authentication: Microsoft OAuth. Requires a connected Microsoft 365 account with access to the relevant Microsoft resources, such as Word, Excel, PowerPoint, OneDrive, SharePoint, Outlook, Calendar, or Teams depending on the tool.

Note: Read Range and Add Table Row only support OneDrive (no driveId parameter). All other Excel tools support both OneDrive and SharePoint via the optional driveId parameter.

Workbook Operations

Create and manage Excel workbooks in OneDrive or SharePoint.

Create Workbook

Create a new, blank Excel workbook (.xlsx) in OneDrive or SharePoint, optionally with named worksheets.

Operation Type: Mutation (Write)

Parameters:

  • fileName string (required): The name of the workbook to create, including the .xlsx extension (e.g. "Q3 Report.xlsx")
  • siteId string (optional): SharePoint site ID to save into its default document library. Provide siteId, driveId, or neither (OneDrive).
  • driveId string (optional): A specific document library drive ID to save into. Omit or null to use the signed-in user's OneDrive.
  • parentItemId string (optional): The drive item ID of the folder to save into. Omit or null to save to the drive root.
  • worksheetNames array of strings (optional): Names for the worksheets to create. Omit or null for a single default "Sheet1".
  • conflictBehavior string (optional, default: "replace"): What to do if a file with the same name exists: "replace" (default), "rename", or "fail".

Returns:

  • id string: ID of the created workbook
  • name string: Final file name (may differ if renamed)
  • webUrl string (nullable): URL to view the workbook in the browser
  • size int (nullable): File size in bytes

Example Usage:

{
  "fileName": "Q3 Report.xlsx",
  "worksheetNames": ["Summary", "Data", "Charts"],
  "conflictBehavior": "rename"
}

Sheet Operations

Manage worksheets (tabs) within an Excel workbook.

List Worksheets

List the worksheets (tabs) in an Excel workbook, including their position and visibility.

Operation Type: Query (Read)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • worksheets array of objects: The worksheets in the workbook
    • id string: Worksheet ID
    • name string: Worksheet name
    • position int (nullable): Zero-based position of the worksheet in the workbook
    • visibility string (nullable): Visibility: Visible, Hidden, or VeryHidden

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX"
}

Add Worksheet

Add a new worksheet (tab) to an Excel workbook.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
  • name string (optional): Name for the new worksheet. Omit or null to let Excel choose a default name.

Returns:

  • id string: ID of the created worksheet
  • name string: Name of the created worksheet
  • position int (nullable): Zero-based position of the worksheet in the workbook
  • visibility string (nullable): Visibility: Visible, Hidden, or VeryHidden

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "name": "Q4 Data"
}

Update Worksheet

Rename, reposition, or change the visibility of a worksheet.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or current name (e.g. "Sheet1")
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
  • name string (optional): New name for the worksheet. Omit or null to leave unchanged.
  • position int (optional): New zero-based position for the worksheet. Omit or null to leave unchanged.
  • visibility string (optional): New visibility: "Visible", "Hidden", or "VeryHidden". Omit or null to leave unchanged.

Returns:

  • id string: Worksheet ID
  • name string: Worksheet name after the update
  • position int (nullable): Zero-based position after the update
  • visibility string (nullable): Visibility after the update

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "name": "January",
  "position": 0
}

Delete Worksheet

Delete a worksheet from an Excel workbook.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name to delete (e.g. "Sheet1")
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • deleted boolean: Whether the worksheet was deleted successfully

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "OldSheet"
}

Range Operations

Read and write cell values, formulas, and formats in a worksheet range.

Read Range

Read a range of cells from an Excel workbook, returning raw values, formatted text, and formulas.

Operation Type: Query (Read)

Parameters:

  • fileId string (required): The OneDrive file ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name (e.g. "Sheet1")
  • range string (required): Cell range in A1 notation (e.g. "A1:D10")

Returns:

  • address string (nullable): Resolved range address
  • rowCount int (nullable): Number of rows in the range
  • columnCount int (nullable): Number of columns in the range
  • values array of arrays (nullable): Cell values as a 2D array
  • text array of string arrays (nullable): Formatted text values as a 2D array
  • formulas array of string arrays (nullable): Cell formulas as a 2D array

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "range": "A1:C10"
}

Update Range

Write values, formulas, or number formats to a range of cells. At least one of values, formulas, or numberFormat must be provided.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name (e.g. "Sheet1")
  • range string (required): Cell range in A1 notation (e.g. "A1:D10"). Must match the shape of the values/formulas provided.
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
  • values array of arrays (optional): Cell values as a 2D array matching the range dimensions. Omit or null to leave values unchanged.
  • formulas array of string arrays (optional): Cell formulas as a 2D array (e.g. [["=A1+B1"]]). Omit or null to leave formulas unchanged.
  • numberFormat array of string arrays (optional): Number formats as a 2D array (e.g. [["0.00%"]]). Omit or null to leave formats unchanged.

Returns:

  • address string (nullable): Resolved range address
  • rowCount int (nullable): Number of rows in the range
  • columnCount int (nullable): Number of columns in the range

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "range": "A1:B2",
  "values": [
    ["Name", "Score"],
    ["Alice", 95]
  ]
}

Clear Range

Clear the contents, formats, or both from a range of cells.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name (e.g. "Sheet1")
  • range string (required): Cell range in A1 notation (e.g. "A1:D10")
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
  • applyTo string (optional, default: "All"): What to clear: "All" (default), "Formats", or "Contents" (values only).

Returns:

  • cleared boolean: Whether the range was cleared successfully

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "range": "A1:D10",
  "applyTo": "Contents"
}

Table Operations

Create and manage structured tables and their rows within an Excel workbook.

List Tables

List the tables in an Excel workbook, optionally scoped to a single worksheet.

Operation Type: Query (Read)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
  • worksheetIdOrName string (optional): Worksheet ID or name to scope the listing to a single sheet. Omit or null to list all tables in the workbook.

Returns:

  • tables array of objects: The tables in the workbook or worksheet
    • id string: Table ID
    • name string: Table name
    • showHeaders boolean (nullable): Whether the header row is shown
    • showTotals boolean (nullable): Whether the totals row is shown
    • style string (nullable): Table style name

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1"
}

Add Table

Create a table over a range of cells in a worksheet.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name that contains the range (e.g. "Sheet1")
  • address string (required): The range the table covers, in A1 notation (e.g. "A1:D5")
  • hasHeaders boolean (required, default: true): Whether the first row of the range is a header row
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • id string: ID of the created table
  • name string: Name of the created table
  • showHeaders boolean (nullable): Whether the header row is shown
  • style string (nullable): Table style name

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "address": "A1:D10",
  "hasHeaders": true
}

Delete Table

Delete a table from an Excel workbook. The underlying cell values remain after deletion.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • tableIdOrName string (required): Table ID or name to delete (e.g. "Table1")
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • deleted boolean: Whether the table was deleted successfully

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "tableIdOrName": "SalesData"
}

List Table Rows

List the data rows of a table in an Excel workbook.

Operation Type: Query (Read)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • tableIdOrName string (required): Table ID or name to read rows from (e.g. "Table1")
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • rows array of objects: The data rows of the table
    • index int (nullable): Zero-based index of the row within the table
    • values array of arrays (nullable): Row values (a single-row 2D array)

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "tableIdOrName": "SalesData"
}

Add Table Row

Add one or more rows to an existing table in an Excel workbook.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive file ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name (e.g. "Sheet1")
  • tableIdOrName string (required): Table ID or name within the worksheet (e.g. "Table1")
  • values array of arrays (required): Row values as a 2D array — each inner array is one row and must match the table's column count (e.g. [["Alice", 42], ["Bob", 37]])

Returns:

  • index int (nullable): Zero-based index of the added row
  • values array of arrays (nullable): Values of the added row as returned by the API

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "tableIdOrName": "SalesData",
  "values": [["Alice", "Engineering", 42]]
}

Update Table Row

Update the values of a table row by its zero-based index.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • tableIdOrName string (required): Table ID or name (e.g. "Table1")
  • index int (required): Zero-based index of the data row to update (from List Table Rows)
  • values array of arrays (required): New row values as a single-row 2D array (e.g. [["a", "b", "c"]])
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • index int (nullable): Index of the updated row
  • values array of arrays (nullable): Values of the updated row

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "tableIdOrName": "SalesData",
  "index": 2,
  "values": [["Bob", "Marketing", 55]]
}

Delete Table Row

Delete a table row by its zero-based index from an Excel workbook.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • tableIdOrName string (required): Table ID or name (e.g. "Table1")
  • index int (required): Zero-based index of the data row to delete (from List Table Rows)
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • deleted boolean: Whether the row was deleted successfully

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "tableIdOrName": "SalesData",
  "index": 3
}

Chart Operations

Create, update, and render charts on Excel worksheets.

List Charts

List the charts on a worksheet in an Excel workbook.

Operation Type: Query (Read)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name to list charts from (e.g. "Sheet1")
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • charts array of objects: The charts on the worksheet
    • id string: Chart ID
    • name string: Chart name
    • height number (nullable): Chart height in points
    • width number (nullable): Chart width in points
    • top number (nullable): Distance from the top of the worksheet in points
    • left number (nullable): Distance from the left of the worksheet in points

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1"
}

Add Chart

Add a chart to a worksheet from a range of data.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name to add the chart to (e.g. "Sheet1")
  • type string (required): Chart type, e.g. "ColumnClustered", "ColumnStacked", "BarClustered", "Line", "LineMarkers", "Pie".
  • sourceData string (required): The range that holds the chart data, in A1 notation (e.g. "A1:B10")
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
  • seriesBy string (optional): How to plot the series: "Auto" (default), "Columns", or "Rows". Omit or null for Auto.

Returns:

  • id string: ID of the created chart
  • name string: Name of the created chart
  • height number (nullable): Chart height in points
  • width number (nullable): Chart width in points
  • top number (nullable): Distance from the top of the worksheet in points
  • left number (nullable): Distance from the left of the worksheet in points

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "type": "ColumnClustered",
  "sourceData": "A1:B10",
  "seriesBy": "Columns"
}

Update Chart

Rename or resize/reposition a chart on a worksheet.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name that contains the chart (e.g. "Sheet1")
  • chartName string (required): The current name (or ID) of the chart to update
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
  • name string (optional): New name for the chart. Omit or null to leave unchanged.
  • height number (optional): New height in points. Omit or null to leave unchanged.
  • width number (optional): New width in points. Omit or null to leave unchanged.
  • top number (optional): New distance from the top of the worksheet in points. Omit or null to leave unchanged.
  • left number (optional): New distance from the left of the worksheet in points. Omit or null to leave unchanged.

Returns:

  • id string: Chart ID
  • name string: Chart name after the update
  • height number (nullable): Chart height in points
  • width number (nullable): Chart width in points
  • top number (nullable): Distance from the top of the worksheet in points
  • left number (nullable): Distance from the left of the worksheet in points

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "chartName": "Chart 1",
  "name": "Q3 Revenue",
  "height": 300,
  "width": 500
}

Delete Chart

Delete a chart from a worksheet in an Excel workbook.

Operation Type: Mutation (Write)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name that contains the chart (e.g. "Sheet1")
  • chartName string (required): The name (or ID) of the chart to delete
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.

Returns:

  • deleted boolean: Whether the chart was deleted successfully

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "chartName": "Chart 1"
}

Get Chart Image

Render a worksheet chart as a base64-encoded PNG image.

Operation Type: Query (Read)

Parameters:

  • fileId string (required): The OneDrive/SharePoint drive item ID of the Excel workbook
  • worksheetIdOrName string (required): Worksheet ID or name that contains the chart (e.g. "Sheet1")
  • chartName string (required): The name (or ID) of the chart to render
  • driveId string (optional): The drive ID containing the workbook (for SharePoint files). Omit or null to use the signed-in user's OneDrive.
  • width int (optional): Desired image width in pixels. Omit or null for the default size.
  • height int (optional): Desired image height in pixels. Omit or null for the default size.
  • fittingMode string (optional): How the chart fits the requested dimensions: "Fit", "FitAndCenter", or "Fill". Only applied when both width and height are set.

Returns:

  • base64Image string (nullable): The chart rendered as a base64-encoded PNG string
  • dataUri string (nullable): The image as a data URI (data:image/png;base64,...)

Example Usage:

{
  "fileId": "01ABCDEFGHIJKLMNOPQRSTUVWX",
  "worksheetIdOrName": "Sheet1",
  "chartName": "Q3 Revenue",
  "width": 800,
  "height": 600,
  "fittingMode": "Fit"
}