Manage workbooks and sheets via the REST API

Retrieve workbook metadata, create and rename sheets, switch the active sheet, and rename the workbook itself using these five REST endpoints.

GridOS organises your data into a workbook that contains one or more named sheets. The endpoints on this page let you inspect the current workbook state and perform structural operations — creating sheets, renaming them, switching which one is active, and renaming the workbook itself. None of these operations touch cell data.

GET /api/workbook

Retrieve the current workbook’s name, the list of all sheet names, and which sheet is currently active. Use this to sync your client state before making structural changes.

Response

workbook_name · string

The display name of the open workbook.

active_sheet · string

The name of the sheet that is currently active.

sheets · array of strings

Ordered list of all sheet names in the workbook.

Example

GET /api/workbook

Response

{
  "workbook_name": "My Financial Model",
  "active_sheet": "Income Statement",
  "sheets": ["Income Statement", "Balance Sheet", "Cash Flow"]
}

---

POST /workbook/sheet

Create a new sheet in the workbook. If you omit name, GridOS generates one automatically (e.g. Sheet2). The new sheet is added to the end of the sheet list but does not become the active sheet automatically.

Request

name · string

The desired name for the new sheet. Must be unique within the workbook. If omitted, a name is auto-generated.

Response

sheet · string

The name of the newly created sheet.

sheets · array of strings

Updated ordered list of all sheet names.

active_sheet · string

The sheet that is currently active (unchanged by this call).

Example

POST /workbook/sheet
{
  "name": "Cash Flow"
}

Response

{
  "sheet": "Cash Flow",
  "sheets": ["Income Statement", "Balance Sheet", "Cash Flow"],
  "active_sheet": "Income Statement"
}

---

POST /workbook/sheet/rename

Rename an existing sheet. All internal references and chart associations follow the rename automatically.

Request

old_name · string · required

The current name of the sheet to rename.

new_name · string · required

The replacement name. Must be unique within the workbook.

Response

sheet · string

The new name of the renamed sheet.

sheets · array of strings

Updated ordered list of all sheet names.

active_sheet · string

The currently active sheet (updated to the new name if the active sheet was renamed).

Example

POST /workbook/sheet/rename
{
  "old_name": "Cash Flow",
  "new_name": "Cash Flow Statement"
}

Response

{
  "sheet": "Cash Flow Statement",
  "sheets": ["Income Statement", "Balance Sheet", "Cash Flow Statement"],
  "active_sheet": "Income Statement"
}

---

POST /workbook/sheet/activate

Switch the active sheet. Subsequent agent calls and grid reads that do not specify a sheet parameter will target this sheet.

Request

name · string · required

The name of the sheet to make active. The sheet must already exist.

Response

sheet · string

The name of the now-active sheet.

sheets · array of strings

Current ordered list of all sheet names.

active_sheet · string

The name of the active sheet (same as sheet).

Example

POST /workbook/sheet/activate
{
  "name": "Balance Sheet"
}

Response

{
  "sheet": "Balance Sheet",
  "sheets": ["Income Statement", "Balance Sheet", "Cash Flow Statement"],
  "active_sheet": "Balance Sheet"
}

Activating a sheet does not modify any cell data. It only changes the default target for subsequent API calls that omit the sheet parameter.

---

POST /workbook/rename

Rename the workbook itself. The new name is reflected in file exports and the workbook UI header.

Request

name · string · required

The new display name for the workbook. Must be a non-empty string.

Response

workbook_name · string

The updated workbook name.

Errors

Status	Meaning
400	The provided name is invalid (e.g. empty string).

Example

POST /workbook/rename
{
  "name": "Acme Corp — FY2026 Model"
}

Response

{
  "workbook_name": "Acme Corp — FY2026 Model"
}