Jupyter Notebooks · Capability

Jupyter Notebook Server REST API

REST API for the Jupyter Notebook server, providing access to notebook contents, kernels, kernel specs, sessions, and terminals. Used by clients to drive interactive computing workflows.

Run with Naftiko JupyterNotebooksAPI

What You Can Do

GET
Getcontents — Get contents at a path
/contents/{path}
PUT
Savecontents — Save or upload contents at a path
/contents/{path}
PATCH
Renamecontents — Rename or move contents
/contents/{path}
POST
Createcontents — Create a new file or directory
/contents/{path}
DELETE
Deletecontents — Delete contents at a path
/contents/{path}
GET
Listcheckpoints — List checkpoints for a file
/contents/{path}/checkpoints
POST
Createcheckpoint — Create a new checkpoint
/contents/{path}/checkpoints
POST
Restorecheckpoint — Restore a file to a checkpoint
/contents/{path}/checkpoints/{checkpoint_id}
DELETE
Deletecheckpoint — Delete a checkpoint
/contents/{path}/checkpoints/{checkpoint_id}
GET
Listkernels — List running kernels
/kernels
POST
Startkernel — Start a new kernel
/kernels
GET
Getkernel — Get kernel info
/kernels/{kernel_id}
DELETE
Shutdownkernel — Shut down a kernel
/kernels/{kernel_id}
POST
Interruptkernel — Interrupt a kernel
/kernels/{kernel_id}/interrupt
POST
Restartkernel — Restart a kernel
/kernels/{kernel_id}/restart
GET
Listkernelspecs — List installed kernel specs
/kernelspecs
GET
Listsessions — List active sessions
/sessions
POST
Createsession — Create a new session
/sessions
GET
Getsession — Get a session
/sessions/{session_id}
PATCH
Updatesession — Update a session
/sessions/{session_id}
DELETE
Deletesession — Delete a session
/sessions/{session_id}
GET
Listterminals — List active terminals
/terminals
POST
Startterminal — Start a new terminal
/terminals
GET
Getterminal — Get a terminal
/terminals/{terminal_id}
DELETE
Stopterminal — Stop a terminal
/terminals/{terminal_id}

MCP Tools

getcontents

Get contents at a path

read-only idempotent
savecontents

Save or upload contents at a path

idempotent
renamecontents

Rename or move contents

createcontents

Create a new file or directory

deletecontents

Delete contents at a path

idempotent
listcheckpoints

List checkpoints for a file

read-only idempotent
createcheckpoint

Create a new checkpoint

restorecheckpoint

Restore a file to a checkpoint

deletecheckpoint

Delete a checkpoint

idempotent
listkernels

List running kernels

read-only idempotent
startkernel

Start a new kernel

getkernel

Get kernel info

read-only idempotent
shutdownkernel

Shut down a kernel

idempotent
interruptkernel

Interrupt a kernel

restartkernel

Restart a kernel

listkernelspecs

List installed kernel specs

read-only idempotent
listsessions

List active sessions

read-only idempotent
createsession

Create a new session

getsession

Get a session

read-only idempotent
updatesession

Update a session

deletesession

Delete a session

idempotent
listterminals

List active terminals

read-only idempotent
startterminal

Start a new terminal

getterminal

Get a terminal

read-only idempotent
stopterminal

Stop a terminal

idempotent

Capability Spec

jupyter-notebooks-capability.yaml Raw ↑ 
naftiko: 1.0.0-alpha2
info:
  label: Jupyter Notebook Server REST API
  description: REST API for the Jupyter Notebook server, providing access to notebook contents, kernels, kernel specs, sessions,
    and terminals. Used by clients to drive interactive computing workflows.
  tags:
  - Jupyter
  - Notebooks
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: jupyter-notebooks
    baseUri: http://localhost:8888/api
    description: Jupyter Notebook Server REST API HTTP API.
    authentication:
      type: bearer
      token: '{{JUPYTER_NOTEBOOKS_TOKEN}}'
    resources:
    - name: contents-path
      path: /contents/{path}
      operations:
      - name: getcontents
        method: GET
        description: Get contents at a path
        inputParameters:
        - name: type
          in: query
          type: string
        - name: format
          in: query
          type: string
        - name: content
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: savecontents
        method: PUT
        description: Save or upload contents at a path
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: renamecontents
        method: PATCH
        description: Rename or move contents
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createcontents
        method: POST
        description: Create a new file or directory
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletecontents
        method: DELETE
        description: Delete contents at a path
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contents-path-checkpoints
      path: /contents/{path}/checkpoints
      operations:
      - name: listcheckpoints
        method: GET
        description: List checkpoints for a file
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createcheckpoint
        method: POST
        description: Create a new checkpoint
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contents-path-checkpoints-checkpoint-id
      path: /contents/{path}/checkpoints/{checkpoint_id}
      operations:
      - name: restorecheckpoint
        method: POST
        description: Restore a file to a checkpoint
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletecheckpoint
        method: DELETE
        description: Delete a checkpoint
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: kernels
      path: /kernels
      operations:
      - name: listkernels
        method: GET
        description: List running kernels
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: startkernel
        method: POST
        description: Start a new kernel
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: kernels-kernel-id
      path: /kernels/{kernel_id}
      operations:
      - name: getkernel
        method: GET
        description: Get kernel info
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: shutdownkernel
        method: DELETE
        description: Shut down a kernel
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: kernels-kernel-id-interrupt
      path: /kernels/{kernel_id}/interrupt
      operations:
      - name: interruptkernel
        method: POST
        description: Interrupt a kernel
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: kernels-kernel-id-restart
      path: /kernels/{kernel_id}/restart
      operations:
      - name: restartkernel
        method: POST
        description: Restart a kernel
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: kernelspecs
      path: /kernelspecs
      operations:
      - name: listkernelspecs
        method: GET
        description: List installed kernel specs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: sessions
      path: /sessions
      operations:
      - name: listsessions
        method: GET
        description: List active sessions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createsession
        method: POST
        description: Create a new session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: sessions-session-id
      path: /sessions/{session_id}
      operations:
      - name: getsession
        method: GET
        description: Get a session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatesession
        method: PATCH
        description: Update a session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deletesession
        method: DELETE
        description: Delete a session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: terminals
      path: /terminals
      operations:
      - name: listterminals
        method: GET
        description: List active terminals
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: startterminal
        method: POST
        description: Start a new terminal
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: terminals-terminal-id
      path: /terminals/{terminal_id}
      operations:
      - name: getterminal
        method: GET
        description: Get a terminal
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: stopterminal
        method: DELETE
        description: Stop a terminal
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: jupyter-notebooks-rest
    description: REST adapter for Jupyter Notebook Server REST API.
    resources:
    - path: /contents/{path}
      name: getcontents
      operations:
      - method: GET
        name: getcontents
        description: Get contents at a path
        call: jupyter-notebooks.getcontents
        outputParameters:
        - type: object
          mapping: $.
    - path: /contents/{path}
      name: savecontents
      operations:
      - method: PUT
        name: savecontents
        description: Save or upload contents at a path
        call: jupyter-notebooks.savecontents
        outputParameters:
        - type: object
          mapping: $.
    - path: /contents/{path}
      name: renamecontents
      operations:
      - method: PATCH
        name: renamecontents
        description: Rename or move contents
        call: jupyter-notebooks.renamecontents
        outputParameters:
        - type: object
          mapping: $.
    - path: /contents/{path}
      name: createcontents
      operations:
      - method: POST
        name: createcontents
        description: Create a new file or directory
        call: jupyter-notebooks.createcontents
        outputParameters:
        - type: object
          mapping: $.
    - path: /contents/{path}
      name: deletecontents
      operations:
      - method: DELETE
        name: deletecontents
        description: Delete contents at a path
        call: jupyter-notebooks.deletecontents
        outputParameters:
        - type: object
          mapping: $.
    - path: /contents/{path}/checkpoints
      name: listcheckpoints
      operations:
      - method: GET
        name: listcheckpoints
        description: List checkpoints for a file
        call: jupyter-notebooks.listcheckpoints
        outputParameters:
        - type: object
          mapping: $.
    - path: /contents/{path}/checkpoints
      name: createcheckpoint
      operations:
      - method: POST
        name: createcheckpoint
        description: Create a new checkpoint
        call: jupyter-notebooks.createcheckpoint
        outputParameters:
        - type: object
          mapping: $.
    - path: /contents/{path}/checkpoints/{checkpoint_id}
      name: restorecheckpoint
      operations:
      - method: POST
        name: restorecheckpoint
        description: Restore a file to a checkpoint
        call: jupyter-notebooks.restorecheckpoint
        outputParameters:
        - type: object
          mapping: $.
    - path: /contents/{path}/checkpoints/{checkpoint_id}
      name: deletecheckpoint
      operations:
      - method: DELETE
        name: deletecheckpoint
        description: Delete a checkpoint
        call: jupyter-notebooks.deletecheckpoint
        outputParameters:
        - type: object
          mapping: $.
    - path: /kernels
      name: listkernels
      operations:
      - method: GET
        name: listkernels
        description: List running kernels
        call: jupyter-notebooks.listkernels
        outputParameters:
        - type: object
          mapping: $.
    - path: /kernels
      name: startkernel
      operations:
      - method: POST
        name: startkernel
        description: Start a new kernel
        call: jupyter-notebooks.startkernel
        outputParameters:
        - type: object
          mapping: $.
    - path: /kernels/{kernel_id}
      name: getkernel
      operations:
      - method: GET
        name: getkernel
        description: Get kernel info
        call: jupyter-notebooks.getkernel
        outputParameters:
        - type: object
          mapping: $.
    - path: /kernels/{kernel_id}
      name: shutdownkernel
      operations:
      - method: DELETE
        name: shutdownkernel
        description: Shut down a kernel
        call: jupyter-notebooks.shutdownkernel
        outputParameters:
        - type: object
          mapping: $.
    - path: /kernels/{kernel_id}/interrupt
      name: interruptkernel
      operations:
      - method: POST
        name: interruptkernel
        description: Interrupt a kernel
        call: jupyter-notebooks.interruptkernel
        outputParameters:
        - type: object
          mapping: $.
    - path: /kernels/{kernel_id}/restart
      name: restartkernel
      operations:
      - method: POST
        name: restartkernel
        description: Restart a kernel
        call: jupyter-notebooks.restartkernel
        outputParameters:
        - type: object
          mapping: $.
    - path: /kernelspecs
      name: listkernelspecs
      operations:
      - method: GET
        name: listkernelspecs
        description: List installed kernel specs
        call: jupyter-notebooks.listkernelspecs
        outputParameters:
        - type: object
          mapping: $.
    - path: /sessions
      name: listsessions
      operations:
      - method: GET
        name: listsessions
        description: List active sessions
        call: jupyter-notebooks.listsessions
        outputParameters:
        - type: object
          mapping: $.
    - path: /sessions
      name: createsession
      operations:
      - method: POST
        name: createsession
        description: Create a new session
        call: jupyter-notebooks.createsession
        outputParameters:
        - type: object
          mapping: $.
    - path: /sessions/{session_id}
      name: getsession
      operations:
      - method: GET
        name: getsession
        description: Get a session
        call: jupyter-notebooks.getsession
        outputParameters:
        - type: object
          mapping: $.
    - path: /sessions/{session_id}
      name: updatesession
      operations:
      - method: PATCH
        name: updatesession
        description: Update a session
        call: jupyter-notebooks.updatesession
        outputParameters:
        - type: object
          mapping: $.
    - path: /sessions/{session_id}
      name: deletesession
      operations:
      - method: DELETE
        name: deletesession
        description: Delete a session
        call: jupyter-notebooks.deletesession
        outputParameters:
        - type: object
          mapping: $.
    - path: /terminals
      name: listterminals
      operations:
      - method: GET
        name: listterminals
        description: List active terminals
        call: jupyter-notebooks.listterminals
        outputParameters:
        - type: object
          mapping: $.
    - path: /terminals
      name: startterminal
      operations:
      - method: POST
        name: startterminal
        description: Start a new terminal
        call: jupyter-notebooks.startterminal
        outputParameters:
        - type: object
          mapping: $.
    - path: /terminals/{terminal_id}
      name: getterminal
      operations:
      - method: GET
        name: getterminal
        description: Get a terminal
        call: jupyter-notebooks.getterminal
        outputParameters:
        - type: object
          mapping: $.
    - path: /terminals/{terminal_id}
      name: stopterminal
      operations:
      - method: DELETE
        name: stopterminal
        description: Stop a terminal
        call: jupyter-notebooks.stopterminal
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: jupyter-notebooks-mcp
    transport: http
    description: MCP adapter for Jupyter Notebook Server REST API for AI agent use.
    tools:
    - name: getcontents
      description: Get contents at a path
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.getcontents
      with:
        type: tools.type
        format: tools.format
        content: tools.content
      inputParameters:
      - name: type
        type: string
        description: type
      - name: format
        type: string
        description: format
      - name: content
        type: integer
        description: content
      outputParameters:
      - type: object
        mapping: $.
    - name: savecontents
      description: Save or upload contents at a path
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: jupyter-notebooks.savecontents
      outputParameters:
      - type: object
        mapping: $.
    - name: renamecontents
      description: Rename or move contents
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.renamecontents
      outputParameters:
      - type: object
        mapping: $.
    - name: createcontents
      description: Create a new file or directory
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.createcontents
      outputParameters:
      - type: object
        mapping: $.
    - name: deletecontents
      description: Delete contents at a path
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: jupyter-notebooks.deletecontents
      outputParameters:
      - type: object
        mapping: $.
    - name: listcheckpoints
      description: List checkpoints for a file
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.listcheckpoints
      outputParameters:
      - type: object
        mapping: $.
    - name: createcheckpoint
      description: Create a new checkpoint
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.createcheckpoint
      outputParameters:
      - type: object
        mapping: $.
    - name: restorecheckpoint
      description: Restore a file to a checkpoint
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.restorecheckpoint
      outputParameters:
      - type: object
        mapping: $.
    - name: deletecheckpoint
      description: Delete a checkpoint
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: jupyter-notebooks.deletecheckpoint
      outputParameters:
      - type: object
        mapping: $.
    - name: listkernels
      description: List running kernels
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.listkernels
      outputParameters:
      - type: object
        mapping: $.
    - name: startkernel
      description: Start a new kernel
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.startkernel
      outputParameters:
      - type: object
        mapping: $.
    - name: getkernel
      description: Get kernel info
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.getkernel
      outputParameters:
      - type: object
        mapping: $.
    - name: shutdownkernel
      description: Shut down a kernel
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: jupyter-notebooks.shutdownkernel
      outputParameters:
      - type: object
        mapping: $.
    - name: interruptkernel
      description: Interrupt a kernel
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.interruptkernel
      outputParameters:
      - type: object
        mapping: $.
    - name: restartkernel
      description: Restart a kernel
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.restartkernel
      outputParameters:
      - type: object
        mapping: $.
    - name: listkernelspecs
      description: List installed kernel specs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.listkernelspecs
      outputParameters:
      - type: object
        mapping: $.
    - name: listsessions
      description: List active sessions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.listsessions
      outputParameters:
      - type: object
        mapping: $.
    - name: createsession
      description: Create a new session
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.createsession
      outputParameters:
      - type: object
        mapping: $.
    - name: getsession
      description: Get a session
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.getsession
      outputParameters:
      - type: object
        mapping: $.
    - name: updatesession
      description: Update a session
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.updatesession
      outputParameters:
      - type: object
        mapping: $.
    - name: deletesession
      description: Delete a session
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: jupyter-notebooks.deletesession
      outputParameters:
      - type: object
        mapping: $.
    - name: listterminals
      description: List active terminals
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.listterminals
      outputParameters:
      - type: object
        mapping: $.
    - name: startterminal
      description: Start a new terminal
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebooks.startterminal
      outputParameters:
      - type: object
        mapping: $.
    - name: getterminal
      description: Get a terminal
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebooks.getterminal
      outputParameters:
      - type: object
        mapping: $.
    - name: stopterminal
      description: Stop a terminal
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: jupyter-notebooks.stopterminal
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    JUPYTER_NOTEBOOKS_TOKEN: JUPYTER_NOTEBOOKS_TOKEN