Add Worksheet
Add a blank worksheet to the open workbook. It becomes the active sheet; get its id from get-sheets. Tableau Studio assigns the new sheet a generated name; pass index to choose the tab position, or omit it to append the sheet at the end.
This tool is not read-only and not idempotent. Each call adds another blank worksheet to the live Tableau Studio session, so repeating the call is not a no-op.
APIs called
This tool acts on the workbook open in the running Tableau Studio instance, not on the Tableau Cloud or Tableau Server REST API. Under the hood this is a call to the local Tableau Studio External Client API — a REST API the running Tableau Studio instance serves at http://127.0.0.1:<port>/v<x>, where <x> is the latest API version. There are no OAuth scopes: the call is authorized by the running Tableau Studio instance's per-session bearer token over the loopback interface.
- Settles on which Tableau Studio session to target before anything is sent. Resolved in-process (not an API call).
- Asks Tableau Studio to add a blank worksheet to the open workbook. Requires a connected Tableau Studio session with a workbook open; authorized by that session's loopback bearer token. The request carries no body;
index, when supplied, is sent as a query parameter.POST /v<x>/workbook/worksheets:new— create a blank worksheet (append, or insert atindexwhen given). API reference
Optional arguments
session
Identifier of the target Tableau Studio session. When omitted, the session is resolved automatically (for example, when exactly one Tableau Studio instance is connected).
Example
"studio-1"
With no session given and no Tableau Studio instance running, or more than one running, the tool reports an error rather than picking one; the multiple-instance error lists the session IDs to choose from. A session that names an instance which is not among the running ones is refused the same way.
index
0-based tab position for the new worksheet. Integer. Range: 0 and above. When omitted, the worksheet is appended at the end of the tab strip.
Tab position
0 inserts before the first existing tab, shifting the others to the right. A value greater than or equal to the current number of tabs appends at the end, the same as omitting index.
Example
2
Notes and caveats
- The result does not include the generated name. The tool reports that the worksheet was added (or that the request is still being applied), not what Tableau Studio named it. Use
get-sheetsto see the names in the open workbook. - A request that has been accepted but not finished is reported as such. When Tableau Studio answers before the change has settled, the result says a new worksheet was requested and is still being applied instead of claiming it completed.
Example results
Worksheet added
{ "message": "Added a blank worksheet." }
Accepted, still being applied
{ "message": "Requested a new worksheet; Desktop is still applying it." }
Related
get-sheets— lists worksheet names in the open workbook, including the generated name of the sheet just added.get-xml— reads the new worksheet's structure once you know its name.apply-worksheet— replaces an existing worksheet with prepared content; it does not create the blank sheet this tool adds.