Notebooks API

Notebook APIs manage Git-backed notebook workspaces, notebook files, supporting authoring files, notebook links, version history, kernel profiles, dedicated workers, and streamed cell execution.

info

All endpoints are mounted under /api/v1.0. Paths below omit that prefix for readability.

Base Path

/engagement/spaces/{space_slug}/notebooks

All endpoints require authentication and access to the target space.

Workspace Endpoints

Method	Endpoint	Description
GET	/engagement/spaces/{space_slug}/notebooks/workspaces	List notebook workspaces.
POST	/engagement/spaces/{space_slug}/notebooks/workspaces	Create a workspace.
PATCH	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}	Update workspace metadata, default repository, visibility, owner, or query connectors.
GET	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/access	Read workspace sharing settings.
PUT	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/access	Replace workspace sharing settings.
POST	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/archive	Archive a workspace.

Workspace visibility is space, private, or shared. Shared workspaces can grant view or manage access to users and teams. Workspaces can also carry authoring_query_connector_ids for governed query access while authoring.

Create Workspace

{
  "name": "Risk notebook review",
  "default_repository_id": "repository-uuid",
  "default_branch": "main",
  "owner_user_id": "user-uuid",
  "visibility": "shared",
  "authoring_query_connector_ids": ["connector-uuid"]
}

Workspace File Endpoints

Method	Endpoint	Description
GET	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/files?ref=main	List notebook files in a workspace repository branch.
POST	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/files	Create a notebook file.
GET	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/file?ref=main&path=notebooks/a.ipynb	Read a notebook file.
PUT	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/file	Save a notebook file and create a version record.
GET	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/authoring-file?ref=main&path=README.md	Read a notebook or text authoring file.
POST	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/authoring-files	Create a notebook or text authoring file.
PUT	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/authoring-file	Save a notebook or text authoring file.
POST	/engagement/spaces/{space_slug}/notebooks/workspaces/{workspace_id}/authoring-file/rename	Rename an authoring file.

Notebook payloads use Jupyter notebook JSON. Text authoring files use kind: "text" with content; notebook files use kind: "notebook" with notebook.

Save Notebook File

{
  "path": "notebooks/risk-review.ipynb",
  "branch": "main",
  "base_sha": "optional-current-file-sha",
  "notebook": {
    "cells": [],
    "metadata": {},
    "nbformat": 4,
    "nbformat_minor": 5
  },
  "commit_message": "Update risk review notebook"
}

Repository File Compatibility

The API also exposes repository-addressed file endpoints for older clients:

Method	Endpoint	Description
GET	/engagement/spaces/{space_slug}/notebooks/repositories/{repository_id}/files?ref=main	List files by repository.
POST	/engagement/spaces/{space_slug}/notebooks/repositories/{repository_id}/files	Create a notebook by repository.
GET	/engagement/spaces/{space_slug}/notebooks/repositories/{repository_id}/file?ref=main&path=notebooks/a.ipynb	Read a notebook by repository.
PUT	/engagement/spaces/{space_slug}/notebooks/repositories/{repository_id}/file	Save a notebook by repository.

Prefer workspace-addressed endpoints for new integrations.

Links And Versions

Method	Endpoint	Description
GET	/engagement/spaces/{space_slug}/notebooks/documents/{notebook_id}/links	List links from a notebook to products, analyses, repositories, or use cases.
POST	/engagement/spaces/{space_slug}/notebooks/documents/{notebook_id}/links	Create a notebook link.
DELETE	/engagement/spaces/{space_slug}/notebooks/documents/{notebook_id}/links/{link_id}	Delete a notebook link.
GET	/engagement/spaces/{space_slug}/notebooks/documents/{notebook_id}/versions	List saved Git versions for a notebook.

target_type is one of product, analysis, repository, or use_case.

Kernels, Workers, And Sessions

Method	Endpoint	Description
GET	/engagement/spaces/{space_slug}/notebooks/kernel-profiles	List available kernel profiles.
GET	/engagement/spaces/{space_slug}/notebooks/worker-resource-classes	List enabled notebook worker resource classes.
GET	/engagement/spaces/{space_slug}/notebooks/workers	List current user's workers. Supports include_stopped and workspace_id.
POST	/engagement/spaces/{space_slug}/notebooks/workers	Start a dedicated notebook worker.
DELETE	/engagement/spaces/{space_slug}/notebooks/workers/{worker_id}	Stop a dedicated notebook worker.
POST	/engagement/spaces/{space_slug}/notebooks/sessions	Create a kernel session.
DELETE	/engagement/spaces/{space_slug}/notebooks/sessions/{session_id}	Delete a kernel session.
POST	/engagement/spaces/{space_slug}/notebooks/sessions/{session_id}/interrupt	Interrupt session execution.
POST	/engagement/spaces/{space_slug}/notebooks/sessions/{session_id}/restart	Restart a session.
POST	/engagement/spaces/{space_slug}/notebooks/sessions/{session_id}/execute/stream	Stream cell execution events as SSE.

Worker backends are docker, kubernetes, or external. Worker status is starting, ready, busy, stopping, stopped, or failed.

Start Worker Or Session

{
  "workspace_id": "workspace-uuid",
  "repository_kind": "analysis",
  "branch": "main",
  "path": "notebooks/risk-review.ipynb",
  "kernel_name": "python3",
  "kernel_profile_id": "python3",
  "resource_class_id": "standard"
}

Execute Cell Stream

{
  "code": "print('hello')",
  "cell_index": 0
}

The response is text/event-stream. Normal execution events use the notebook_event event name. The stream ends with final_response or emits error with a safe message and status code.

Error Notes

Status	Meaning
400	Invalid workspace settings, resource class settings, file path, or request payload.
403	The user cannot view or manage the workspace or runtime.
404	Workspace, repository, file, notebook, worker, or session was not found in the space.
409	Git base SHA or worker/session state conflict.
503	Runtime gateway, worker startup, or kernel execution dependency is unavailable.

Related

• Authoring Workspace Access API
• Query Editor API
• Documents API