Skip to main content
POST /excel/generate produces .xlsx workbooks from a single prompt. The agent can write raw data, apply formulas, style headers, freeze panes, create charts, and build multi-sheet workbooks in one call.

​
What the Excel agent can do

Ordered roughly from “used in almost every workbook” to specialized:
  • Multi-sheet workbooks — create, rename, reorder, delete sheets; set which sheet is active when the workbook opens.
  • Data entry — bulk writes, per-cell updates, append rows at the bottom of existing data, delete rows or columns in place.
  • Formulas — cross-sheet references, aggregations (SUM, AVERAGE, MAX, MIN, COUNT, COUNTIF, AVERAGEIF), lookup functions (VLOOKUP, INDEX/MATCH), statistical (STDEV), and computed columns that derive from other columns.
  • Number formatting — currency, percentage, date, custom patterns, thousand separators, per-column or per-range.
  • Cell and range styling — fonts, sizes, bold/italic/underline, fill colors, borders (per-side), alignment, wrap, merge cells, cell-level hyperlinks.
  • Conditional formatting — thresholds, color scales, data bars, icon sets — ideal for status columns, score highlighting, KPI dashboards.
  • Charts — column, bar, line, pie, doughnut, area, scatter, bubble, combo, stock, radar. Automatic axis titles, legends, data labels; chart sits on the same or a different sheet.
  • Pivot-style summary tables — aggregated totals, averages, or counts grouped by one or more columns, with optional totals rows.
  • View settings — freeze panes (header rows / left columns), auto-filters, column widths, row heights, hide/show rows or columns.
  • Tables and sorting — apply sort on a range, find-and-replace values, manipulate text columns (upper/lower/title case, split, concat).
  • Images — embed uploaded images anchored to a cell or range, replace / delete existing images.
  • Data validation — dropdowns, numeric ranges, custom formulas.
  • Sheet protection — lock a sheet or specific ranges.
The agent chooses the right combination for your prompt; you don’t need to enumerate actions yourself. Say what the workbook is for and the agent figures out the structure, formatting, and formulas.

​
Quickstart

resp = requests.post(
    f"{API}/excel/generate",
    headers={"X-API-Key": KEY},
    json={"prompt": "Create a sales report with Q1-Q4 revenue by region"},
)
print(resp.json()["download_url"])
Opens as a .xlsx with headers, rows, formulas for totals and averages, and at least one chart.

​
Common patterns

​
Working from an uploaded CSV

Upload the source first, then reference it in the prompt: 
# 1. Upload the data
with open("historicals.csv", "rb") as f:
    upload = requests.post(
        f"{API}/files",
        headers={"X-API-Key": KEY},
        files={"file": f},
        data={"purpose": "reference"},
    ).json()

# 2. Generate, passing the file_id
resp = requests.post(
    f"{API}/excel/generate",
    headers={"X-API-Key": KEY},
    json={
        "prompt": "Build a 5-year forecast using this historicals data",
        "data_sources": [{"file_id": upload["file_id"], "kind": "csv"}],
    },
)
The agent reads the CSV, detects the schema, and either uses it directly or summarizes + projects from it.

​
Editing an existing workbook

Pass init_file and the agent edits in-place instead of creating fresh: 
# 1. Upload an existing xlsx
upload = requests.post(
    f"{API}/files",
    headers={"X-API-Key": KEY},
    files={"file": open("q3_draft.xlsx", "rb")},
    data={"purpose": "init"},
).json()

# 2. Edit it
resp = requests.post(
    f"{API}/excel/generate",
    headers={"X-API-Key": KEY},
    json={
        "prompt": "Add a 'Churn' column with month-over-month percentage",
        "init_file": upload["file_id"],
    },
)

​
Financial models

For serious financial modeling (three-statement, DCF, LBO), hint the intent and the agent loads a specialized template: 
resp = requests.post(
    f"{API}/excel/generate",
    headers={"X-API-Key": KEY},
    json={
        "prompt": (
            "Build a 3-statement financial model for a SaaS company. "
            "5-year horizon starting FY26. USD. "
            "Include Income Statement, Balance Sheet, Cash Flow Statement, "
            "Assumptions tab, and KPI summary."
        ),
    },
)
Output includes:
  • Linked formulas across sheets (=Assumptions.C5)
  • Balance check (Assets = Liabilities + Equity)
  • Cash reconciliation (CFS ending cash = BS cash)
  • Input cells styled yellow for clarity
  • Number formatting per column type

​
Analyze without editing

If you just want to ask a question about an uploaded workbook and get a JSON answer back (no file produced), use POST /excel/analyze: 
resp = requests.post(
    f"{API}/excel/analyze",
    headers={"X-API-Key": KEY},
    json={
        "file_id": upload["file_id"],
        "prompt": "What was the total Q3 revenue?",
    },
)
# → {"answer": "Total Q3 revenue was $4.2M across 12 regions.", ...}

​
Resuming and iterating

Pass run_id to build incrementally: 
# Turn 1 — create the base
r1 = requests.post(f"{API}/excel/generate", headers=headers, json={
    "prompt": "Create a workforce headcount tracker with columns Name, Role, Dept, Start Date, Salary",
}).json()

# Turn 2 — add features on top
r2 = requests.post(f"{API}/excel/generate", headers=headers, json={
    "run_id": r1["run_id"],
    "prompt": "Now add a 'Tenure (months)' column with formula =DATEDIF(E2, TODAY(), 'M')",
}).json()

# Turn 3 — restyle
r3 = requests.post(f"{API}/excel/generate", headers=headers, json={
    "run_id": r1["run_id"],
    "prompt": "Apply dark navy header row and zebra striping",
}).json()
Turn 2 and 3 are much cheaper because the agent already remembers the sheet structure, column names, and row count.

​
Things the agent handles well

  • Formulas (cross-sheet, INDEX/MATCH, VLOOKUP, aggregations)
  • Number formatting (currency, percentage, date, custom)
  • Conditional formatting (status columns, score thresholds)
  • Charts (column, bar, line, pie, combo, stock, bubble)
  • Pivot-style summaries (aggregated totals, averages)
  • Title banners with merged cells + fills
  • Freeze panes, filters, column widths

​
Things to be aware of

  • Output cap: 200 rows per WRITE_DATA before the agent splits into batches. Large data imports should stream via data_sources rather than embedding in the prompt.
  • No macros / VBA. Cell-level formulas only.
  • Agent may choose different chart types than you’d expect if the prompt is ambiguous. Specify (“use a bar chart”) if it matters.
  • Placeholder data gets generated when the prompt asks for data the agent doesn’t have. It’ll note the choice in the summary field.