Jupyter Notebook Jupyter Kernel Gateway API

naftiko: 1.0.0-alpha2
info:
  label: Jupyter Notebook Jupyter Kernel Gateway API
  description: 'REST API for the Jupyter Kernel Gateway, a web server that provides headless access to Jupyter kernels. The
    Kernel Gateway supports two modes: jupyter-websocket mode (default) which provides a Jupyter Notebook server-compatible
    API for kernel management, and notebook-http mode which maps notebook cells to HTTP endpoints. This spec covers the jupyter-websocket
    mode API.'
  tags:
  - Jupyter
  - Notebook
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: jupyter-notebook
    baseUri: http://localhost:8888/api
    description: Jupyter Notebook Jupyter Kernel Gateway API HTTP API.
    authentication:
      type: apikey
      in: header
      name: Authorization
      value: '{{JUPYTER_NOTEBOOK_TOKEN}}'
    resources:
    - name: api
      path: /api
      operations:
      - name: getapiinfo
        method: GET
        description: Jupyter Notebook Get API info
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-kernels
      path: /api/kernels
      operations:
      - name: listkernels
        method: GET
        description: Jupyter Notebook List running kernels
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: startkernel
        method: POST
        description: Jupyter Notebook Start a kernel
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-kernels-kernel-id
      path: /api/kernels/{kernel_id}
      operations:
      - name: getkernel
        method: GET
        description: Jupyter Notebook Get kernel information
        inputParameters:
        - name: kernel_id
          in: path
          type: string
          required: true
          description: Unique identifier for the kernel.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: shutdownkernel
        method: DELETE
        description: Jupyter Notebook Shut down a kernel
        inputParameters:
        - name: kernel_id
          in: path
          type: string
          required: true
          description: Unique identifier for the kernel.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-kernels-kernel-id-interrupt
      path: /api/kernels/{kernel_id}/interrupt
      operations:
      - name: interruptkernel
        method: POST
        description: Jupyter Notebook Interrupt a kernel
        inputParameters:
        - name: kernel_id
          in: path
          type: string
          required: true
          description: Unique identifier for the kernel.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-kernels-kernel-id-restart
      path: /api/kernels/{kernel_id}/restart
      operations:
      - name: restartkernel
        method: POST
        description: Jupyter Notebook Restart a kernel
        inputParameters:
        - name: kernel_id
          in: path
          type: string
          required: true
          description: Unique identifier for the kernel.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-kernelspecs
      path: /api/kernelspecs
      operations:
      - name: listkernelspecs
        method: GET
        description: Jupyter Notebook List kernel specifications
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-kernelspecs-kernel-name
      path: /api/kernelspecs/{kernel_name}
      operations:
      - name: getkernelspec
        method: GET
        description: Jupyter Notebook Get a kernel specification
        inputParameters:
        - name: kernel_name
          in: path
          type: string
          required: true
          description: Name of the kernel specification.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: jupyter-notebook-rest
    description: REST adapter for Jupyter Notebook Jupyter Kernel Gateway API.
    resources:
    - path: /api
      name: getapiinfo
      operations:
      - method: GET
        name: getapiinfo
        description: Jupyter Notebook Get API info
        call: jupyter-notebook.getapiinfo
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/kernels
      name: listkernels
      operations:
      - method: GET
        name: listkernels
        description: Jupyter Notebook List running kernels
        call: jupyter-notebook.listkernels
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/kernels
      name: startkernel
      operations:
      - method: POST
        name: startkernel
        description: Jupyter Notebook Start a kernel
        call: jupyter-notebook.startkernel
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/kernels/{kernel_id}
      name: getkernel
      operations:
      - method: GET
        name: getkernel
        description: Jupyter Notebook Get kernel information
        call: jupyter-notebook.getkernel
        with:
          kernel_id: rest.kernel_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/kernels/{kernel_id}
      name: shutdownkernel
      operations:
      - method: DELETE
        name: shutdownkernel
        description: Jupyter Notebook Shut down a kernel
        call: jupyter-notebook.shutdownkernel
        with:
          kernel_id: rest.kernel_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/kernels/{kernel_id}/interrupt
      name: interruptkernel
      operations:
      - method: POST
        name: interruptkernel
        description: Jupyter Notebook Interrupt a kernel
        call: jupyter-notebook.interruptkernel
        with:
          kernel_id: rest.kernel_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/kernels/{kernel_id}/restart
      name: restartkernel
      operations:
      - method: POST
        name: restartkernel
        description: Jupyter Notebook Restart a kernel
        call: jupyter-notebook.restartkernel
        with:
          kernel_id: rest.kernel_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/kernelspecs
      name: listkernelspecs
      operations:
      - method: GET
        name: listkernelspecs
        description: Jupyter Notebook List kernel specifications
        call: jupyter-notebook.listkernelspecs
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/kernelspecs/{kernel_name}
      name: getkernelspec
      operations:
      - method: GET
        name: getkernelspec
        description: Jupyter Notebook Get a kernel specification
        call: jupyter-notebook.getkernelspec
        with:
          kernel_name: rest.kernel_name
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: jupyter-notebook-mcp
    transport: http
    description: MCP adapter for Jupyter Notebook Jupyter Kernel Gateway API for AI agent use.
    tools:
    - name: getapiinfo
      description: Jupyter Notebook Get API info
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebook.getapiinfo
      outputParameters:
      - type: object
        mapping: $.
    - name: listkernels
      description: Jupyter Notebook List running kernels
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebook.listkernels
      outputParameters:
      - type: object
        mapping: $.
    - name: startkernel
      description: Jupyter Notebook Start a kernel
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebook.startkernel
      outputParameters:
      - type: object
        mapping: $.
    - name: getkernel
      description: Jupyter Notebook Get kernel information
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebook.getkernel
      with:
        kernel_id: tools.kernel_id
      inputParameters:
      - name: kernel_id
        type: string
        description: Unique identifier for the kernel.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: shutdownkernel
      description: Jupyter Notebook Shut down a kernel
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: jupyter-notebook.shutdownkernel
      with:
        kernel_id: tools.kernel_id
      inputParameters:
      - name: kernel_id
        type: string
        description: Unique identifier for the kernel.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: interruptkernel
      description: Jupyter Notebook Interrupt a kernel
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebook.interruptkernel
      with:
        kernel_id: tools.kernel_id
      inputParameters:
      - name: kernel_id
        type: string
        description: Unique identifier for the kernel.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: restartkernel
      description: Jupyter Notebook Restart a kernel
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: jupyter-notebook.restartkernel
      with:
        kernel_id: tools.kernel_id
      inputParameters:
      - name: kernel_id
        type: string
        description: Unique identifier for the kernel.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: listkernelspecs
      description: Jupyter Notebook List kernel specifications
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebook.listkernelspecs
      outputParameters:
      - type: object
        mapping: $.
    - name: getkernelspec
      description: Jupyter Notebook Get a kernel specification
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jupyter-notebook.getkernelspec
      with:
        kernel_name: tools.kernel_name
      inputParameters:
      - name: kernel_name
        type: string
        description: Name of the kernel specification.
        required: true
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    JUPYTER_NOTEBOOK_TOKEN: JUPYTER_NOTEBOOK_TOKEN