Marimo-based interactive Python notebooks backed by Sail (Spark) sessions.
/me/teams/notebooksList my team notebooks
Returns all notebooks shared with the current user's teams that they are
permitted to view, aggregated across every team they belong to.
Parameters
limitinteger
The maximum number of items to list.
"int32"0100100pageinteger
The page number to retrieve (1-indexed). Used with limit to support offset-based pagination.
"int32"11sortBystring
The notebook field to sort by.
"name""status""updatedAt""updatedAt"sortDirectionstring
The direction to sort notebooks.
"asc""desc""desc"Responses
Responses
A list of notebooks the current user can access via their teams is returned.
/workloads/notebooksList notebooks
Returns a paginated list of the notebooks owned by the requesting member. Notebooks shared with the member's teams are returned by ListMyTeamNotebooks.
Parameters
limitinteger
The maximum number of items to list.
"int32"0100100pageinteger
The page number to retrieve (1-indexed). Used with limit to support offset-based pagination.
"int32"11sortBystring
The notebook field to sort by.
"name""status""updatedAt""updatedAt"sortDirectionstring
The direction to sort notebooks.
"asc""desc""desc"Responses
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. Name a sourceUploadId to start it from an uploaded marimo file instead of an empty one.
Request Body
Responses
Responses
The notebook was created successfully.
/workloads/notebooks/source/uploadUpload a notebook source
Step one of starting a notebook from a marimo .py file. Returns a short-lived authorization to upload the file directly to the workspace storage of the given compute profile; the file does not pass through this API. Send it as the provider's form upload with the returned parameters, then name the returned uploadId in CreateNotebook, to create a notebook from it, or in ImportNotebookSource, to replace the file of an existing notebook on a compute profile in the same network. Only the member who made an upload can use it. An upload that is never used changes nothing; that member's next upload clears it once it is a day old.
Request Body
Responses
Responses
A short-lived authorization to upload a notebook source to workspace storage.
/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 proxy authentication URL for embedding the notebook UI as an iframe. The notebook must be running. Used as the iframe src, the URL has the session proxy validate the embedded JWT, set a same-site access cookie, and redirect to the notebook. The URL and the cookie share one lifetime, returned as expiresAt; call this operation again before then and load the new URL with redirect=none to renew the cookie without reloading 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}/logs/streamIssue a notebook log stream
Issues a short-lived token and URL for streaming the notebook pod's live log from the customer-side session proxy. Returns 409 while the notebook's pod is not yet running (retry shortly) or when the cluster requires re-provisioning for live logs; 410 when the notebook's resources have been cleaned up.
Responses
Responses
Connection details for the notebook's live log stream.
/workloads/notebooks/{notebook}/pingRecord notebook activity
Records the authenticated user's presence while a notebook is open in the browser. Updates the client activity timestamp read by the idle-timeout monitor. It is one of the activity signals: a request through the session proxy and a running cell count as well, so a notebook is not stopped for a missed ping while a cell runs. The notebook must be running. Intended to be called on the frontend's heartbeat interval while the notebook iframe is rendered.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
Activity recorded.
/workloads/notebooks/{notebook}/sourceDescribe a notebook's source
Returns what is saved of the notebook's source file. It is absent until the notebook has saved or imported one. A running notebook saves as it changes, so this describes its last save.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
What is saved of the notebook's source file.
/workloads/notebooks/{notebook}/source/importImport an uploaded notebook source
Replaces an existing notebook's source with a file uploaded with CreateNotebookSourceUpload, for a compute profile in the notebook's network. Checks that the file is a marimo notebook and makes it the notebook's source, which the notebook starts from next time. To start a new notebook from a file instead, name the upload in CreateNotebook. The check reads only the start of the file, and the file is copied within workspace storage, so it does not pass through this API. This replaces the notebook's cells: download them first to keep them. A copy of the replaced file is also kept in workspace storage, beside the notebook's own, which this API does not read back. The notebook must be stopped, and the named upload must be waiting.
Parameters
notebookrequired
A notebook ID.
Request Body
Responses
Responses
The notebook's source after the import.
/workloads/notebooks/{notebook}/source/downloadDownload a notebook source
Returns a short-lived URL that downloads the notebook's source file directly from workspace storage; the file does not pass through this API. Allowed in any status. While a session runs, the file is its last save, which can be a few seconds behind the editor.
Parameters
notebookrequired
A notebook ID.
Responses
Responses
A short-lived URL that downloads the notebook source from workspace storage.
/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"0100100pageinteger
The page number to retrieve (1-indexed). Used with limit to support offset-based pagination.
"int32"11Responses
Responses
A list of notebooks accessible to the team is returned.