> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.overtenai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Excel guide

> Generate and edit .xlsx spreadsheets — formulas, tables, charts, financial models.

`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

```python theme={null}
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:

```python theme={null}
# 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:

```python theme={null}
# 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:

```python theme={null}
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`](/guides/analyze):

```python theme={null}
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:

```python theme={null}
# 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.