Marimo-based interactive Python notebooks backed by Sail (Spark) sessions.
/workloads/notebooksList notebooks
Returns a paginated list of notebooks accessible to the requesting member, including notebooks they own and notebooks shared with their teams. Organization administrators see all notebooks.
Parameters
limitinteger
The maximum number of items to list.
"int32"0100100Responses
Responses
A paginated list of notebooks is returned.
/workloads/notebooksCreate a notebook
Creates a new Marimo notebook associated with a workload configuration. The notebook starts in stopped state. Call StartNotebook to provision the Sail and Marimo pods.
Request Body
Responses
Responses
The notebook was created successfully.
/workloads/notebooks/{notebook}Describe a notebook
Returns the full details of a notebook, including its current status, configuration, associated workload config, and team access list.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
Notebook details with normalized entity references.
/workloads/notebooks/{notebook}Delete a notebook
Permanently removes a notebook and its team assignments. If the notebook is currently running, it will be stopped before deletion.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
The requested operation was done successfully.
/workloads/notebooks/{notebook}Update a notebook
Modifies a notebook's display name, description, or idle timeout. The workload configuration can only be changed when the notebook is stopped.
Parameters
notebookrequired
A notebook ID.
Request Body
Responses
Responses
The notebook was updated successfully.
/workloads/notebooks/{notebook}/startStart a notebook
Provisions the Sail (Spark Connect) and Marimo pods for this notebook. The notebook must be in stopped state. Status transitions to starting immediately; the session proxy URL becomes available once status reaches running.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
Notebook start initiated; status has transitioned to starting.
/workloads/notebooks/{notebook}/stopStop a notebook
Tears down the Sail and Marimo pods for this notebook. The notebook must be in running state. Status transitions to stopping immediately; a stopped status confirms teardown is complete.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
Notebook stop initiated; status has transitioned to stopping.
/workloads/notebooks/{notebook}/openOpen a notebook
Returns a short-lived proxy authentication URL for embedding the notebook UI as an iframe. The notebook must be in running, idle, or detached state. The URL is valid for 5 minutes and is intended to be used once as the iframe src; the session proxy validates the embedded JWT, sets a same-site access cookie, and redirects to the notebook.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
A short-lived proxy authentication URL for embedding the notebook as an iframe.
/workloads/notebooks/{notebook}/pingRecord notebook activity
Records the authenticated user's presence while a notebook is open in the browser. Updates the activity timestamp used by the idle-timeout monitor, keeping the notebook session alive while the user has it open. The notebook must be in running, idle, or detached state. Intended to be called periodically (e.g. every 60 seconds) by the frontend while the notebook iframe is rendered.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
Activity recorded.
/workloads/notebooks/{notebook}/teamsList notebook teams
Returns the teams that have been granted access to the specified notebook.
Parameters
notebookrequired
A notebook ID.
limitinteger
The maximum number of items to list.
"int32"0100100Responses
Responses
A list of teams associated with the notebook is returned.
/workloads/notebooks/{notebook}/teamsAdd teams to a notebook
Grants one or more teams access to a notebook. Team members will be able to view and open the notebook (in read-only mode if the owner is active).
Parameters
notebookrequired
A notebook ID.
Request Body
Responses
Responses
The teams were added to the notebook successfully.
/workloads/notebooks/{notebook}/teams/{team}Remove a team from a notebook
Revokes a team's access to a notebook. Team members will no longer be able to view or open the notebook unless they have access through another team or are the notebook owner.
Parameters
notebookrequired
A notebook ID.
teamrequired
The team ID.
Responses
Responses
The team was removed from the notebook successfully.
/workloads/teams/{team}/notebooksList team notebooks
Returns a paginated list of notebooks that the specified team has been granted access to.
Parameters
limitinteger
The maximum number of items to list.
"int32"0100100Responses
Responses
A list of notebooks accessible to the team is returned.