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

# Excel agent API: let your AI agent create and edit Excel files

> An API for your AI agent to create and edit Excel (.xlsx) files with real formulas, checked before delivery, through the SDK or MCP.

With Doconda's Excel agent API, your AI agent creates and edits Excel files: ask for `format: "xlsx"` with a sentence and
you get an `.xlsx` with real formulas (not pasted numbers), assumptions in their own cells and no calculation errors,
plus its PDF. To change an Excel file that already exists, `operation: "edit"` changes only what you ask.

## Steps

1. Put your API key (dashboard → **API keys**) in `DOCONDA_API_KEY` and install the SDK (`pip install doconda` or
   `npm install @doconda/sdk`).
2. Create the Excel file from a sentence:

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  from pathlib import Path
  from doconda import Doconda

  doconda = Doconda()  # reads the key from DOCONDA_API_KEY
  doc = doconda.documents.create(
      format="xlsx",
      prompt="12-month revenue forecast: 1,000 customers at the start, 5% monthly growth and €20 per customer",
  )
  Path("forecast.xlsx").write_bytes(doconda.documents.download(doc["id"], "xlsx"))
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  import { readFile, writeFile } from "node:fs/promises"
  import { Doconda } from "@doconda/sdk"

  const doconda = new Doconda()
  const doc = await doconda.documents.create({
    format: "xlsx",
    prompt: "12-month revenue forecast: 1,000 customers at the start, 5% monthly growth and €20 per customer",
  })
  await writeFile("forecast.xlsx", await doconda.documents.download(doc.id, "xlsx"))
  ```
</CodeGroup>

3. Edit an Excel file you already have (uploaded with `files.upload`, or one Doconda made, by its `doc_…`):

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  file = doconda.files.upload("sales.xlsx")
  edited = doconda.documents.create(operation="edit", file=file["id"], prompt="Add a column with each month's margin")
  edits = doconda.documents.report(edited["id"])["edits"]
  ```

  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  const file = await doconda.files.upload(await readFile("sales.xlsx"), "sales.xlsx")
  const edited = await doconda.documents.create({ operation: "edit", file: file.id, prompt: "Add a column with each month's margin" })
  const { edits } = await doconda.documents.report(edited.id)
  ```
</CodeGroup>

4. Or give the tools to your agent, for example with the remote MCP server:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# pip install openai-agents
import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main():
    async with MCPServerStreamableHttp(
        name="doconda",
        params={
            "url": "https://api.eu.doconda.com/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['DOCONDA_API_KEY']}"},
        },
        client_session_timeout_seconds=300,
    ) as doconda:
        agent = Agent(name="Documents", model="gpt-5", mcp_servers=[doconda])
        result = await Runner.run(agent, "Make me an Excel file with the event budget")
        print(result.final_output)


asyncio.run(main())
```

Without MCP, `doconda.tools()` gives the same tools for any model with function calling.

## What you get back

* An `.xlsx` with formulas: change an assumption and the sheet recalculates. Also its PDF.
* `status`: `ready`, `ready_with_warnings`, `needs_review` or `failed` (not charged).
* A report (`documents.report(id)`): figures that don't come from your request or your sources are removed or flagged,
  and for an edit, each change with its before and after (`edits`).

## FAQ

<AccordionGroup>
  <Accordion title="Do edits keep the formulas?">
    Yes. In `standard` and `best` changes use real formulas and the rest of the sheet stays identical. In `fast`, and
    always with `.xls`, text and basic style are changed.
  </Accordion>

  <Accordion title="Can I give it my own data?">
    Yes. Upload your files and pass their ids in `sources` (up to 5 documents: Word, PowerPoint, Excel, PDF, TXT or
    Markdown).
  </Accordion>

  <Accordion title="What about an Excel file with errors I already have?">
    Review it with `operation="review"`: it detects formulas with errors (`#REF!`, `#DIV/0!`…), broken references and
    numbers stored as text, among others. See [Review](/en/guides/review).
  </Accordion>

  <Accordion title="How much does it cost?">
    Creating from a sentence: €0.15 in `fast`, €0.50 in `standard`, €1.50 in `best`. Editing: €0.10, €0.30 or €1.00.
    See [pricing](/en/guides/account#pricing).
  </Accordion>
</AccordionGroup>

## Keep reading

* [Generate an Excel file with formulas from an LLM](/en/solutions/excel-formulas-llm).
* [Edit](/en/guides/edit) and [Create](/en/guides/create).
* [Doconda in your agent](/en/agents/introduction).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.