Skip to main content
POST /excel/generate turns a natural-language prompt into a fully formatted .xlsx workbook. The agent writes data, applies formulas, styles headers, freezes panes, creates charts, and builds multi-sheet workbooks in a single call — no templates or manual formatting required. Use it to automate sales reports, financial models, data dashboards, and any other spreadsheet you’d otherwise build by hand.

​
Request parameters

​
prompt
string
required
Natural-language description of the workbook you want. Up to 10,000 characters. Be specific about structure, columns, and intent — the more context you give, the better the output.
​
run_id
string
Resume an existing run. Pass the run_id from a previous response to add columns, restyle, or extend the workbook. Follow-up turns are faster and cheaper because the agent already knows the sheet structure.
​
init_file
string
file_id of an existing .xlsx to edit in-place instead of creating a new workbook. Upload the file first with POST /files (purpose: "init").
​
data_sources
array
Reference files to read data from. Each entry is an object with file_id and kind (e.g., "csv"). The agent reads the schema and uses the data directly.
​
image_assets
array
Images to embed in the workbook. Each entry is an object with image_id and tags. Upload images first with POST /images.
​
async
boolean
default:"false"
Set to true to run the job asynchronously. The response returns a task_id immediately. Use webhook_url to receive the result, or poll GET /tasks/{task_id}.
​
webhook_url
string
URL to receive a POST when the async job completes. See Webhooks.
​
file_name
string
Override the default output filename.
​
idempotency_key
string
Supply a unique key to safely retry requests without producing duplicate runs.

​
Quickstart

1

Generate a workbook

Send a prompt describing what you want. The response includes a download_url for the finished .xlsx.
import requests

API = "https://backend.overtenai.com/api/v1"
KEY = "sk_live_..."

resp = requests.post(
    f"{API}/excel/generate",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"prompt": "Create a sales report with Q1-Q4 revenue by region"},
)
data = resp.json()
print(data["download_url"])
2

Download the file

Fetch the download_url to retrieve the .xlsx. The URL is a signed link valid for 1 hour.

​
Response shape

A successful synchronous response looks like this: 
{
  "run_id": "run_abc123",
  "status": "completed",
  "download_url": "https://storage.overtenai.com/...",
  "summary": "Created a 4-sheet sales report with Q1-Q4 data, regional totals, and a column chart.",
  "credits_used": 45,
  "duration_ms": 18320
}
FieldDescription
run_idUse this to resume the run or export to another format.
download_urlSigned URL for the .xlsx file. Valid for 1 hour.
summaryAgent’s description of what it built.
credits_usedCredits deducted for this call.

​
Common use cases

​
Working from an uploaded CSV

Upload a source file first, then reference it in the prompt. The agent reads the schema and builds the workbook from your data. 
import requests

API = "https://backend.overtenai.com/api/v1"
headers = {"Authorization": f"Bearer {KEY}"}

# 1. Upload the data
with open("historicals.csv", "rb") as f:
    upload = requests.post(
        f"{API}/files",
        headers=headers,
        files={"file": f},
        data={"purpose": "reference"},
    ).json()

# 2. Generate, passing the file_id
resp = requests.post(
    f"{API}/excel/generate",
    headers=headers,
    json={
        "prompt": "Build a 5-year forecast using this historicals data",
        "data_sources": [{"file_id": upload["file_id"], "kind": "csv"}],
    },
)
print(resp.json()["download_url"])

​
Editing an existing workbook

Pass init_file to edit in-place instead of creating a fresh workbook. 
# 1. Upload an existing xlsx
upload = requests.post(
    f"{API}/files",
    headers=headers,
    files={"file": open("q3_draft.xlsx", "rb")},
    data={"purpose": "init"},
).json()

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

​
Financial models

For three-statement models, DCFs, or LBOs, describe your intent and the agent loads a specialized template automatically. 
resp = requests.post(
    f"{API}/excel/generate",
    headers={"Authorization": f"Bearer {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."
        ),
    },
)
The output includes linked formulas across sheets (=Assumptions.C5), a balance check (Assets = Liabilities + Equity), cash reconciliation, yellow-highlighted input cells, and per-column number formatting.

​
Iterating with run_id

Pass run_id to build incrementally. Follow-up turns are much cheaper because the agent already knows the sheet structure, column names, and row count. 
# 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
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()

​
Exporting to other formats

Convert a completed run to PDF, CSV, PNG, or HTML using POST /runs/{run_id}/export. 
export = requests.post(
    f"{API}/runs/{run_id}/export",
    headers=headers,
    json={"format": "pdf"},
)
print(export.json()["download_url"])
Supported export formats for Excel runs: pdf, csv, png, html.

​
What the agent handles well

  • Formulas: cross-sheet references, INDEX/MATCH, VLOOKUP, SUM, COUNTIF, and more
  • Number formatting: currency, percentage, date, custom patterns, thousand separators
  • Conditional formatting: threshold rules, color scales, data bars, icon sets
  • Charts: column, bar, line, pie, doughnut, combo, scatter, bubble, stock, radar
  • Pivot-style summary tables: grouped totals, averages, counts
  • View settings: freeze panes, auto-filters, column widths, row heights

​
Things to be aware of

The agent writes up to 200 rows per WRITE_DATA operation before splitting into batches. For large data imports, pass your file via data_sources rather than describing the data in the prompt.
  • No macros or VBA. The agent uses cell-level formulas only.
  • Placeholder data is generated when the prompt asks for data the agent doesn’t have. The summary field in the response notes when this happens.
  • Chart type selection is agent-driven. If a specific chart type matters, say so explicitly in your prompt (“use a bar chart”).

​
Tips for better results

State the purpose of the workbook first, then describe the structure. “Build a monthly budget tracker for a 10-person team” gives the agent enough context to choose the right columns, formulas, and formatting automatically.
  • Specify currencies, date formats, and fiscal year conventions upfront.
  • Name the sheets you want if the layout matters to you.
  • For financial models, mention the time horizon and accounting basis (e.g., “5-year horizon, accrual, USD”).
  • Ask for async: true on large workbooks to avoid timeout issues.
  • Runs and tasks — understand run_id, task polling, and run lifecycle
  • Async vs sync — when to use async: true and how to poll or receive webhooks
  • Analyze an Excel file — ask questions of an uploaded workbook without producing a new file
  • Credits — how generation costs are calculated