# Jupyter (/integrations/jupyter)

Use [Jupyter](https://jupyter.org/) to manage files, notebooks, kernels, and sessions on a self-hosted Jupyter server.

- List, read, create, upload, rename, copy, or delete files, notebooks, and directories.
- List, start, stop, restart, or interrupt kernels.
- List, create, or delete sessions that bind a notebook path to a kernel.

These operations manage notebook content and runtime lifecycle. Starting a kernel or creating a session does not itself execute notebook cells. Deleting a session also shuts down its associated kernel; save work first. See [Jupyter’s REST API](https://jupyter-server.readthedocs.io/en/latest/developers/rest-api.html#delete--api-sessions-session).

## Use the block \[#usage-instructions]

Browse, read, create, upload, rename, copy, and delete files and notebooks; start, stop, restart, and interrupt kernels; and manage sessions that bind notebooks to kernels.

## Actions \[#actions]

### Jupyter List Contents \[#jupyter-list-contents]

List files, notebooks, and subdirectories at a path on a Jupyter server

#### Input \[#input]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `path` | string | No | Directory path to list, relative to the server root. Leave blank for root. |

#### Output \[#output]

| Parameter | Type | Description |
| - | - | - |
| `items` | array | Directory entries at the requested path |
| ↳ `name` | string | Entry name |
| ↳ `path` | string | Entry path relative to server root |
| ↳ `type` | string | directory, file, or notebook |
| ↳ `writable` | boolean | Whether the entry is writable |
| ↳ `created` | string | Creation timestamp |
| ↳ `lastModified` | string | Last modified timestamp |
| ↳ `size` | number | Size in bytes |
| ↳ `mimetype` | string | MIME type (files only) |
| ↳ `format` | string | json, text, or base64 |
| `path` | string | The listed directory path |

### Jupyter Get Content \[#jupyter-get-content]

Download a file as a stored file, or read structured notebook and directory content

#### Input \[#input-1]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `path` | string | Yes | Path of the file or notebook to read, relative to the server root |

#### Output \[#output-1]

| Parameter | Type | Description |
| - | - | - |
| `file` | file | Downloaded file |
| `text` | string | JSON-stringified notebook or directory content |
| `name` | string | Notebook or directory name |
| `path` | string | Notebook or directory path |
| `mimetype` | string | Notebook or directory MIME type |

### Jupyter Create File \[#jupyter-create-file]

Create a file, notebook, or directory on a Jupyter server

#### Input \[#input-2]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `path` | string | Yes | Path to create, relative to the server root |
| `type` | string | Yes | Type of entry to create: file, notebook, or directory |
| `content` | string | No | Content to write. For a file, plain text. For a notebook, a JSON-stringified nbformat document (defaults to an empty notebook). Ignored for directories. |

#### Output \[#output-2]

| Parameter | Type | Description |
| - | - | - |
| `name` | string | Created entry name |
| `path` | string | Created entry path |
| `type` | string | directory, file, or notebook |
| `createdAt` | string | Creation timestamp |
| `lastModified` | string | Last modified timestamp |

### Jupyter Upload File \[#jupyter-upload-file]

Upload a file to a Jupyter server

#### Input \[#input-3]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `directory` | string | No | Destination directory, relative to the server root. Leave blank to upload to the root directory. |
| `file` | file | No | The file to upload (UserFile object) |
| `fileName` | string | No | Optional filename override |

#### Output \[#output-3]

| Parameter | Type | Description |
| - | - | - |
| `name` | string | Uploaded file name |
| `path` | string | Uploaded file path |
| `size` | number | File size in bytes |
| `lastModified` | string | Last modified timestamp |

### Jupyter Rename Content \[#jupyter-rename-content]

Rename or move a file, notebook, or directory on a Jupyter server

#### Input \[#input-4]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `path` | string | Yes | Current path of the entry, relative to the server root |
| `newPath` | string | Yes | New path for the entry, relative to the server root |

#### Output \[#output-4]

| Parameter | Type | Description |
| - | - | - |
| `name` | string | New entry name |
| `path` | string | New entry path |
| `lastModified` | string | Last modified timestamp |

### Jupyter Delete Content \[#jupyter-delete-content]

Delete a file, notebook, or directory on a Jupyter server

#### Input \[#input-5]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `path` | string | Yes | Path of the entry to delete, relative to the server root |

#### Output \[#output-5]

| Parameter | Type | Description |
| - | - | - |
| `success` | boolean | Whether the entry was deleted |
| `path` | string | Deleted entry path |

### Jupyter Copy Content \[#jupyter-copy-content]

Duplicate a file or notebook into a directory on a Jupyter server

#### Input \[#input-6]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `path` | string | Yes | Destination directory path, relative to the server root |
| `copyFromPath` | string | Yes | Path of the file or notebook to copy, relative to the server root |

#### Output \[#output-6]

| Parameter | Type | Description |
| - | - | - |
| `name` | string | Name of the copied entry |
| `path` | string | Path of the copied entry |
| `createdAt` | string | Creation timestamp |

### Jupyter List Kernels \[#jupyter-list-kernels]

List running kernels on a Jupyter server

#### Input \[#input-7]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |

#### Output \[#output-7]

| Parameter | Type | Description |
| - | - | - |
| `kernels` | array | Running kernels |
| ↳ `id` | string | Kernel ID |
| ↳ `name` | string | Kernel spec name |
| ↳ `lastActivity` | string | Last activity timestamp |
| ↳ `executionState` | string | Kernel execution state |
| ↳ `connections` | number | Active connection count |

### Jupyter Start Kernel \[#jupyter-start-kernel]

Start a new kernel on a Jupyter server

#### Input \[#input-8]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `kernelName` | string | No | Kernel spec name to start (e.g. python3). Defaults to the server default. |

#### Output \[#output-8]

| Parameter | Type | Description |
| - | - | - |
| `id` | string | Kernel ID |
| `name` | string | Kernel spec name |
| `lastActivity` | string | Last activity timestamp |
| `executionState` | string | Kernel execution state |
| `connections` | number | Active connection count |

### Jupyter Stop Kernel \[#jupyter-stop-kernel]

Shut down a running kernel on a Jupyter server

#### Input \[#input-9]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `kernelId` | string | Yes | ID of the kernel to shut down |

#### Output \[#output-9]

| Parameter | Type | Description |
| - | - | - |
| `success` | boolean | Whether the kernel was shut down |
| `kernelId` | string | Shut down kernel ID |

### Jupyter Restart Kernel \[#jupyter-restart-kernel]

Restart a running kernel on a Jupyter server

#### Input \[#input-10]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `kernelId` | string | Yes | ID of the kernel to restart |

#### Output \[#output-10]

| Parameter | Type | Description |
| - | - | - |
| `id` | string | Kernel ID |
| `name` | string | Kernel spec name |
| `lastActivity` | string | Last activity timestamp |
| `executionState` | string | Kernel execution state |
| `connections` | number | Active connection count |

### Jupyter Interrupt Kernel \[#jupyter-interrupt-kernel]

Interrupt a running kernel on a Jupyter server

#### Input \[#input-11]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `kernelId` | string | Yes | ID of the kernel to interrupt |

#### Output \[#output-11]

| Parameter | Type | Description |
| - | - | - |
| `success` | boolean | Whether the interrupt was sent |
| `kernelId` | string | Interrupted kernel ID |

### Jupyter List Kernel Specs \[#jupyter-list-kernel-specs]

List available kernel specs (languages/runtimes) on a Jupyter server

#### Input \[#input-12]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |

#### Output \[#output-12]

| Parameter | Type | Description |
| - | - | - |
| `defaultKernelName` | string | Default kernel spec name |
| `kernelspecs` | array | Available kernel specs |
| ↳ `name` | string | Kernel spec name |
| ↳ `displayName` | string | Human-readable display name |
| ↳ `language` | string | Kernel language |
| ↳ `argv` | array | Launch command arguments |
| ↳ `interruptMode` | string | Interrupt mode |

### Jupyter List Sessions \[#jupyter-list-sessions]

List active sessions (notebook-to-kernel bindings) on a Jupyter server

#### Input \[#input-13]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |

#### Output \[#output-13]

| Parameter | Type | Description |
| - | - | - |
| `sessions` | array | Active sessions |
| ↳ `id` | string | Session ID |
| ↳ `path` | string | Notebook path bound to this session |
| ↳ `name` | string | Session name |
| ↳ `type` | string | Session type |
| ↳ `kernel` | object | Kernel bound to this session |
| ↳ `id` | string | Kernel ID |
| ↳ `name` | string | Kernel spec name |
| ↳ `lastActivity` | string | Last activity timestamp |
| ↳ `executionState` | string | Kernel execution state |
| ↳ `connections` | number | Active connection count |

### Jupyter Create Session \[#jupyter-create-session]

Create a session that binds a notebook path to a (new or existing) kernel

#### Input \[#input-14]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `path` | string | Yes | Notebook path to bind the session to, relative to the server root |
| `kernelName` | string | No | Kernel spec name to start for this session (e.g. python3) |
| `name` | string | No | Optional session name |
| `type` | string | No | Session type, defaults to 'notebook' |

#### Output \[#output-14]

| Parameter | Type | Description |
| - | - | - |
| `id` | string | Session ID |
| `path` | string | Notebook path bound to this session |
| `name` | string | Session name |
| `type` | string | Session type |
| `kernel` | object | Kernel bound to this session |
| ↳ `id` | string | Kernel ID |
| ↳ `name` | string | Kernel spec name |
| ↳ `lastActivity` | string | Last activity timestamp |
| ↳ `executionState` | string | Kernel execution state |
| ↳ `connections` | number | Active connection count |

### Jupyter Delete Session \[#jupyter-delete-session]

Delete a session and shut down its associated kernel on a Jupyter server

#### Input \[#input-15]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `serverUrl` | string | Yes | Base URL of the Jupyter server (e.g. <http://localhost:8888>) |
| `token` | string | Yes | Jupyter server authentication token |
| `sessionId` | string | Yes | ID of the session to delete |

#### Output \[#output-15]

| Parameter | Type | Description |
| - | - | - |
| `success` | boolean | Whether the session was deleted |
| `sessionId` | string | Deleted session ID |