Requests used in the example

This breaks down the calls from SumSheet’s first run — the same f1-api-first-run.mjs script the quick start uses to open a workbook, edit three cells, and save the result. The whole script is on the Verified script page; below is each of its requests, one at a time.

Every request after open goes to the same process

subsetId lives in the running core’s memory, not in the file. If you send the next request to a new process, you’ll get the unknown-subset-session refusal: “open and edit must run in the same process, no changes were made”. So you start the core once and keep talking to it while the workbook is open — how that conversation works is described in the API session.

Open the workbook

{
  "operation": "open_workbook_subset",
  "sourceUri": "file:///absolute/path/input.xlsx",
  "viewport": { "top": 0, "left": 0, "rows": 20, "cols": 12 },
  "requestedBackend": "native-desktop"
}

You take payload.subsetId and payload.activeSheet.path from the response.

requestedBackend here is a request, not a requirement. There are three values: native-desktop, wasm, and service-host. If you ask for something other than what’s actually running, there’s no refusal: the core computes with what it has and says so honestly — with the requested-backend-unavailable warning, and the response carries backendUsed and fallbackUsed. So an example carried over from the desktop app to the browser won’t break, but it also won’t actually compute on the engine it names — what else arrives in every response.

Write text, a number, and a formula

{
  "operation": "apply_cell_edits",
  "subsetId": "subset-...",
  "edits": [
    { "sheetKey": "xl/worksheets/sheet1.xml",
      "row": 0, "col": 0, "inputKind": "text", "input": "SumSheet API" },
    { "sheetKey": "xl/worksheets/sheet1.xml",
      "row": 0, "col": 1, "inputKind": "number", "input": "21" },
    { "sheetKey": "xl/worksheets/sheet1.xml",
      "row": 0, "col": 2, "inputKind": "formula", "input": "=B1*2" }
  ],
  "expectedRevision": 0,
  "viewport": { "top": 0, "left": 0, "rows": 20, "cols": 12 },
  "requestedBackend": "native-desktop"
}

The three edits are sent atomically and create one history entry.

Read the cell

{
  "operation": "read_cell_details",
  "subsetId": "subset-...",
  "row": 0,
  "col": 2,
  "viewport": { "top": 0, "left": 0, "rows": 20, "cols": 12 },
  "requestedBackend": "native-desktop"
}

The value you want is in payload.cell.displayValue, and the formula’s original text is in payload.cell.editText.

Undo and redo

{
  "operation": "replay_workbook_history",
  "subsetId": "subset-...",
  "direction": "undo",
  "viewport": { "top": 0, "left": 0, "rows": 20, "cols": 12 },
  "requestedBackend": "native-desktop"
}

For redo, send the same request with direction: "redo".

Save

{
  "operation": "save_workbook_subset",
  "subsetId": "subset-...",
  "destinationUri": "file:///absolute/path/result.xlsx",
  "preserveCachedValues": true,
  "requestedBackend": "native-desktop"
}

Don’t assemble the URI by hand

In Node.js, use pathToFileURL(path).href. It correctly encodes spaces and non-ASCII characters.

preserveCachedValues decides the fate of the numbers formulas show in the file. The field is required — it has no default.

Value	What ends up in the file	The warning in the response
true	The formulas themselves and the numbers they show: both what came from the original workbook and what the current session recalculated.	cached-formula-values-preserved, if a recalculation is needed somewhere else
false	Only the formulas themselves. The numbers are cleared for every formula in the workbook.	cached-formula-values-omitted

false leaves the file empty for anything that can’t compute

Cleared numbers don’t come back on their own when the file opens: only a recalculation restores them. Excel will recalculate, but a plain viewer or a library parse will show empty cells wherever there’s a formula. Set false only when you’re certain the file will be opened by a program that computes — what the response warns about.

How the file is published

save_workbook_subset doesn’t write over the existing file. The bytes go into a temporary file in the same folder, get flushed to disk, and only then does the temporary file atomically take the target’s place.

So if something fails — a process crash, running out of space, a power cut — the target path ends up with either the whole previous file or the whole new one, never a truncated one. You don’t need to build your own temp files around saving, and the file appearing at the target path already means the write is complete.

Next

• The full list of operations — the Compute Contract reference.
• Verification before the pilot — the Checklist.