MaybeAI Sheet Skill

Full Excel/spreadsheet lifecycle management powered by the MaybeAI platform. Upload files, read and write data, manage worksheets, add charts, apply formatting, and build SQL-assisted pivot/result tables via natural language.

Scripts

Ready-to-run curl examples are in the scripts/ folder. Each script reads credentials from environment variables — no hardcoded tokens.

CODEBLOCK0

Requires: curl and jq. Install jq with brew install jq (macOS) or apt install jq (Linux).

---

Setup

Get your API token

1. 1. Go to https://maybe.ai/user/my-plan in your browser.

(Or click your avatar / name at the bottom-left of the app → My Plan.)

1. 2. Find the API Token card below the plan summary — it shows a masked Bearer token with copy and reveal buttons.
2. Copy the token and set it as an environment variable:

CODEBLOCK1

Required environment variable

Variable	Description
INLINECODE5	Your MaybeAI Bearer token. Get it from maybe.ai/user/my-plan.

Base URL

CODEBLOCK2

All authenticated endpoints require the header:

CODEBLOCK3

---

Quick Reference

User says	Action
"Upload this Excel file"	INLINECODE6
"Import from URL"

POST /api/v1/excel/import_by_url |
| "Read Sheet1 data" | POST /api/v1/excel/read_sheet |
| "List my files" | POST /api/v1/excel/list_files |
| "List worksheets" | POST /api/v1/excel/list_worksheets |
| "Update cells A1:B3" | POST /api/v1/excel/update_range |
| "Replace all data rows but keep headers" | POST /api/v1/excel/update_data_keep_headers |
| "Upsert rows by key, append new ones" | POST /api/v1/excel/update_range_by_lookup |
| "Append new rows" | POST /api/v1/excel/append_rows |
| "Insert 2 rows at row 5" | POST /api/v1/excel/insert_rows |
| "Delete rows 3–5" | POST /api/v1/excel/delete_rows |
| "Add a new worksheet" | POST /api/v1/excel/write_new_worksheet |
| "Add a bar chart" | POST /api/v1/excel/add_chart |
| "Freeze the header row" | POST /api/v1/excel/freeze_panes |
| "Add auto filter" | POST /api/v1/excel/set_auto_filter |
| "Calculate formula =SUM(A1:A10)" | POST /api/v1/excel/calc_formulas |
| "Build a pivot/result sheet from worksheet data" | POST /api/v1/excel/sql/compile then POST /api/v1/excel/sql/write_result |
| "Export/download the file" | GET /api/v1/excel/export/{document_id} |
| "Copy this spreadsheet" | POST /api/v1/excel/copy_excel |

---

API Reference

File Management

Upload Excel File

POST /api/v1/excel/upload
Content-Type: multipart/form-data

file: <xlsx file>
user_id: (optional)

Returns { document_id, uri, ... }. Use document_id (also called uri) in all subsequent calls.

Import File by URL

POST /api/v1/excel/import_by_url
Authorization: Bearer <token>

{ "url": "https://..." }

Downloads the file from the URL into MaybeAI storage. Returns document_id.

List Files

CODEBLOCK6

Search Files

CODEBLOCK7

Rename File

CODEBLOCK8

Delete File

CODEBLOCK9

Export (Download) File

GET /api/v1/excel/export/{document_id}

Returns the raw .xlsx file.

Download File (from GridFS)

CODEBLOCK11

Copy Excel Document

POST /api/v1/excel/copy_excel
Authorization: Bearer <token>

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>" }

---

Reading Data

Get Spreadsheet Data (MOST USEFUL & FREQUENTLY USE) (JSON)

GET /api/v1/excel/spreadsheets/{doc_id}?gid=<sheet_index>

Returns spreadsheet data as JSON. gid selects the worksheet (0-indexed).

View Spreadsheet (HTML)

GET /api/v1/excel/spreadsheets/d/{doc_id}

Returns an HTML preview of the spreadsheet.

List Worksheets

CODEBLOCK15

Read Sheet

POST /api/v1/excel/read_sheet

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>", "worksheet_name": "Sheet1" }

Returns all cell data from the specified worksheet.

Read Headers

POST /api/v1/excel/read_headers

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>?gid=0" }

Use this first for fast schema inspection before writing SQL for pivot/result output.

Worksheet Targeting Rule

• - Do not rely on "sheet" for excelize-mcp-backed read/write calls.
• Use "worksheet_name" when the endpoint supports it, such as read_sheet, update_range, clear_range, and update_data_keep_headers.
• Use ?gid=<sheet_index> inside uri when the endpoint does not expose worksheet_name, such as read_headers, append_rows, and update_range_by_lookup.
• If neither worksheet_name nor ?gid= is provided, the backend resolves to the first worksheet, which is effectively gid=0.

List Versions

CODEBLOCK18

Read Version

POST /api/v1/excel/read_version

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>", "version": 1 }

---

Writing & Editing Data

Update Range

CODEBLOCK20

Use uri: "https://www.maybe.ai/docs/spreadsheets/d/<document_id>?gid=2" instead of worksheet_name if you want to target a sheet by gid.

Update Data Keep Headers

Use this when the sheet already has the correct header row and you want to replace the data rows underneath it without rebuilding column order manually.

CODEBLOCK21

What it does:

• - Keeps the existing header row unchanged and preserves its column order.
• Rewrites data rows using header names, so agents can send list-of-dict data instead of manually ordered row arrays.
• Can preserve formula columns that are not present in data and auto-fill those formulas down.
• Is often easier than update_range when the goal is "replace the table contents but keep the sheet structure".

Update Range by Lookup

Use this for key-based updates or upserts. It is more agent-friendly than low-level update_range when rows should be matched by business keys such as id, sku, or composite keys.

CODEBLOCK22

What it does:

• - Matches existing rows by the on key column(s), then updates only the matching rows.
• Automatically appends unmatched rows as new rows, so one call can do update + append.
• Preserves existing headers and appends new columns to the right if the incoming data contains unseen fields.
• Does not overwrite existing formula cells.
• With override: false, empty values in the incoming data do not blank out existing cells.

Clear Range

CODEBLOCK23

Append Rows

CODEBLOCK24

INLINECODE57 selects the target worksheet from uri. If you omit ?gid=, it appends to the first worksheet.

Choosing the right write API

• - Use append_rows when you have object rows keyed by existing headers and want a simple blind append.
• Use update_data_keep_headers when you have list-of-dict data and want to replace all table rows while keeping row 1, column order, styles, and optional formula columns.
• Use update_range_by_lookup when you need upsert behavior: update rows that match a key and append rows that do not exist yet.
• Use update_range when you truly need exact A1 targeting such as B7:D12, header rewrites, or non-tabular cell edits.
• For non-first worksheets, always set worksheet_name or uri?gid=N explicitly. Otherwise writes can land on the first sheet.

Agent-friendly patterns

• - Easier append than append_rows:

If the agent has object-shaped rows like {"sku":"A1","qty":2,"price":10} and does not want to manually map them into the sheet's column order, prefer update_range_by_lookup for upsert-or-append or update_data_keep_headers for full-table replacement.

• - Easier update than update_range:

If the user says "update rows by order ID" or "sync these records into the sheet", prefer update_range_by_lookup so the agent does not need to read row numbers and construct A1 ranges first.

• - Keep formulas intact:

If the sheet has computed columns like Total or Margin, prefer update_data_keep_headers with preserve_formulas: true or update_range_by_lookup, which avoids overwriting existing formula cells.

Write New Sheet (creates a new workbook)

CODEBLOCK25

Copy Range with Formulas

CODEBLOCK26

Copy Range by Lookup

POST /api/v1/excel/copy_range_by_lookup
Authorization: Bearer <token>

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>?gid=0", "from_range": "A2:D2", "lookup_column": "ID", "on": ["ID"], "skip_if_exists": true }

---

Row & Column Operations

Insert Rows

POST /api/v1/excel/insert_rows
Authorization: Bearer <token>

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>", "worksheet_name": "Sheet1", "start_row": 3, "row_count": 2 }

Inserts row_count blank rows starting at start_row (1-indexed).

Delete Rows

CODEBLOCK29

Move Row

CODEBLOCK30

Move Rows (batch)

CODEBLOCK31

Undo Delete Rows

CODEBLOCK32

Insert Columns

CODEBLOCK33

Delete Columns

CODEBLOCK34

Move Column

CODEBLOCK35

Move Columns (batch)

CODEBLOCK36

Undo Delete Columns

CODEBLOCK37

Add Header Columns

CODEBLOCK38

Set Columns Width

CODEBLOCK39

Set Rows Height

POST /api/v1/excel/set_rows_height
Authorization: Bearer <token>

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>", "worksheet_name": "Sheet1", "start_row": 1, "end_row": 1, "height": 30 }

---

Worksheet Management

Write New Worksheet

CODEBLOCK41

Delete Worksheet

CODEBLOCK42

Rename Worksheet

CODEBLOCK43

Move Worksheet

CODEBLOCK44

Duplicate Worksheet

CODEBLOCK45

List Worksheets (with versions)

POST /api/v1/excel/list_worksheets_version

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>" }

---

Formulas

Calculate Single Formula

CODEBLOCK47

Calculate Multiple Formulas

CODEBLOCK48

Compile SQL for Pivot/Result Output

POST /api/v1/excel/sql/compile
Authorization: Bearer <token>

{
  "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>?gid=2",
  "sql": "select \"Region\", sum(\"Revenue\") as \"Revenue\" from gid_2 group by \"Region\" order by \"Revenue\" desc"
}

Validate SQL against backend SQLite + worksheet/gid rules before writing any output.

Write SQL Result to Worksheet

POST /api/v1/excel/sql/write_result
Authorization: Bearer <token>

{
  "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>?gid=2",
  "sql": "select \"Region\", sum(\"Revenue\") as \"Revenue\" from gid_2 group by \"Region\" order by \"Revenue\" desc",
  "target_worksheet_name": "Pivot_RegionRevenue",
  "target_start_cell": "A1",
  "create_sheet_if_missing": true,
  "clear_target_range": true,
  "include_headers": true
}

Execute SQL and write the pivot/result matrix into a worksheet.

SQL Pivot Workflow

Use this for SQL-assisted pivot/result-table generation from worksheet data. Do not describe it as a general SQL engine on sheets. The recommended path is raw SQL authoring, compile-only validation, then dedicated result writing.

Default sequence:

1. 1. Inspect source worksheet names with POST /api/v1/excel/list_worksheets.
2. Inspect headers with POST /api/v1/excel/read_headers, or inspect a small sample with POST /api/v1/excel/read_sheet and a narrow range_address.
3. Draft SQL using either the worksheet name or a gid_* table reference.
4. Validate SQL with POST /api/v1/excel/sql/compile.
5. If compile succeeds, write the result block with POST /api/v1/excel/sql/write_result.
6. Optionally verify the written output with POST /api/v1/excel/read_sheet.

Table naming rules:

• - SQL can reference a worksheet name directly.
• SQL can reference gid_* such as gid_2.
• INLINECODE90 uses the backend worksheet gid mapping returned by worksheet inspection.
• Quote worksheet names when they contain spaces, for example from "Sales Data".
• Compile first to catch unsupported syntax or unsupported SQL features.

Examples:

CODEBLOCK51

CODEBLOCK52

Important limitations:

• - Not every SQL feature is supported.
• Backend behavior follows the current SQL formula compatibility rules and SQLite-based worksheet resolution.
• INLINECODE92 remains useful for preview/debug of formula-driven work, but it is not the main recommended path for pivot/result output.
• If compile fails, fix the SQL before calling sql/write_result.

Example: Revenue by Region

Inspect headers first:

CODEBLOCK53

CODEBLOCK54

If headers are not enough, read a small sample:

CODEBLOCK55

CODEBLOCK56

Draft SQL:

CODEBLOCK57

Compile before write:

CODEBLOCK58

CODEBLOCK59

Write the result:

CODEBLOCK60

CODEBLOCK61

Verify the final output:

CODEBLOCK62

CODEBLOCK63

Recalculate All Formulas

POST /api/v1/excel/recalculate_formulas
Authorization: Bearer <token>

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>" }

---

Charts

Add Chart

POST /api/v1/excel/add_chart
Authorization: Bearer <token>

{
  "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>",
  "worksheet_name": "Sheet1",
  "cell": "E2",
  "chart": {
    "type": "bar",
    "series": [{ "name": "Sales", "categories": "Sheet1!A2:A10", "values": "Sheet1!B2:B10" }],
    "title": { "name": "Monthly Sales" }
  }
}

Supported chart types: line, bar, col, pie, scatter, area, doughnut, radar.

Edit Chart

CODEBLOCK66

Delete Chart

POST /api/v1/excel/delete_chart
Authorization: Bearer <token>

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>", "worksheet_name": "Sheet1", "cell": "E2" }

---

Pictures

Add Picture

CODEBLOCK68

Read Picture

CODEBLOCK69

Delete Picture

POST /api/v1/excel/delete_picture
Authorization: Bearer <token>

{ "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>", "worksheet_name": "Sheet1", "cell": "D2" }

---

Formatting

Freeze Panes

POST /api/v1/excel/freeze_panes
Authorization: Bearer <token>

{
  "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>",
  "worksheet_name": "Sheet1",
  "freeze_rows": 1,
  "freeze_columns": 0
}

Set freeze_rows: 1 to lock the header row while scrolling.

Set Auto Filter

CODEBLOCK72

Remove Auto Filter

CODEBLOCK73

Set Conditional Formats

POST /api/v1/excel/set_conditional_formats
Authorization: Bearer <token>

{
  "uri": "https://www.maybe.ai/docs/spreadsheets/d/<document_id>",
  "worksheet_name": "Sheet1",
  "formats": [
    {
      "sqref": "B2:B100",
      "type": "cell",
      "criteria": ">",
      "value": "90",
      "format": { "font": { "color": "FF0000" } }
    }
  ]
}

---

Common Workflows

Workflow 1: Upload and read a file

CODEBLOCK75

Workflow 2: Build a SQL-assisted pivot/result sheet

CODEBLOCK76

Workflow 3: Update existing data

CODEBLOCK77

Workflow 4: Bulk data append

CODEBLOCK78

Workflow 5: Refresh a table but keep headers and formulas

CODEBLOCK79

---

Notes

• - uri format: Build uri from the returned document_id as https://www.maybe.ai/docs/spreadsheets/d/{document_id}. Add ?gid={gid} only when the API needs worksheet selection from the URI itself.
• SQL authoring: For pivot/result-table generation, inspect worksheet names first, then use read_headers or a small read_sheet sample before writing SQL. Prefer sql/compile plus sql/write_result over calc_formulas for this workflow.
• SQL table references: Use either the worksheet name or gid_*. Quote worksheet names with spaces, for example "Sales Data".
• Range format: Use Excel-style ranges like A1, A1:B10, A:A.
• Row/column indexing: Row numbers are 1-indexed (row 1 = first data row). Columns use Excel letters (A, B, ...).
• Worksheet targeting is explicit: If you do not pass worksheet_name or ?gid= in uri, many endpoints fall back to the first worksheet. This is the common reason writes appear to go to gid=0.
• Header-aware tools are usually safer for agents: update_data_keep_headers and update_range_by_lookup work with header names instead of raw column positions, which reduces mistakes when sheet layouts change.
• Authentication: Endpoints marked AUTH require Authorization: Bearer <MAYBEAI_API_TOKEN>. Public endpoints work without a token.
• Spreadsheet viewer URL: https://www.maybe.ai/docs/spreadsheets/d/{doc_id} renders a live HTML preview of the file and is the same base format used for request uri values.