Jupyter Notebook Kernels API

openapi: 3.2.0
info:
  title: Jupyter Notebook REST Kernels API
  description: REST API for managing and interacting with Jupyter Notebook servers, including kernels, sessions, contents (notebooks and files), terminals, and kernel specifications. This API is served by the Jupyter Notebook server (or Jupyter Server) and provides programmatic access to all notebook server functionality.
  version: 7.0.0
  license:
    name: BSD-3-Clause
    url: https://opensource.org/licenses/BSD-3-Clause
  contact:
    name: Jupyter Project
    url: https://jupyter.org
    email: jupyter@googlegroups.com
servers:
- url: http://localhost:8888/api
  description: Local Jupyter Notebook server
security:
- token: []
- tokenHeader: []
tags:
- name: Kernels
  description: Kernel lifecycle management including starting, stopping, interrupting, and restarting kernels.
paths:
  /api/kernels:
    get:
      operationId: listKernels
      summary: Jupyter Notebook List running kernels
      description: List all currently running kernels.
      tags:
      - Kernels
      responses:
        '200':
          description: List of running kernels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Kernel'
    post:
      operationId: startKernel
      summary: Jupyter Notebook Start a kernel
      description: Start a new kernel with an optional kernel specification name.
      tags:
      - Kernels
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the kernel spec to use.
                path:
                  type: string
                  description: Working directory for the kernel.
      responses:
        '201':
          description: Kernel started successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Kernel'
  /api/kernels/{kernel_id}:
    get:
      operationId: getKernel
      summary: Jupyter Notebook Get kernel information
      description: Get the model for a specific kernel by its ID.
      tags:
      - Kernels
      parameters:
      - name: kernel_id
        in: path
        required: true
        description: Unique identifier for the kernel.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Kernel model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Kernel'
        '404':
          description: Kernel not found.
    delete:
      operationId: shutdownKernel
      summary: Jupyter Notebook Shut down a kernel
      description: Shut down a running kernel by its ID.
      tags:
      - Kernels
      parameters:
      - name: kernel_id
        in: path
        required: true
        description: Unique identifier for the kernel.
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Kernel shut down successfully.
        '404':
          description: Kernel not found.
  /api/kernels/{kernel_id}/interrupt:
    post:
      operationId: interruptKernel
      summary: Jupyter Notebook Interrupt a kernel
      description: Interrupt a running kernel, stopping any currently executing code.
      tags:
      - Kernels
      parameters:
      - name: kernel_id
        in: path
        required: true
        description: Unique identifier for the kernel.
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Kernel interrupted successfully.
        '404':
          description: Kernel not found.
  /api/kernels/{kernel_id}/restart:
    post:
      operationId: restartKernel
      summary: Jupyter Notebook Restart a kernel
      description: Restart a running kernel. This will kill the current kernel process and start a new one with the same ID.
      tags:
      - Kernels
      parameters:
      - name: kernel_id
        in: path
        required: true
        description: Unique identifier for the kernel.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Kernel restarted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Kernel'
        '404':
          description: Kernel not found.
components:
  schemas:
    Kernel:
      type: object
      description: A running kernel instance.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the kernel.
        name:
          type: string
          description: Name of the kernel specification.
        last_activity:
          type: string
          format: date-time
          description: Timestamp of the last activity on the kernel.
        execution_state:
          type: string
          description: Current execution state of the kernel.
          enum:
          - starting
          - idle
          - busy
          - restarting
          - dead
        connections:
          type: integer
          description: Number of active connections to this kernel.
      required:
      - id
      - name
      - last_activity
      - execution_state
      - connections
  securitySchemes:
    token:
      type: apiKey
      in: query
      name: token
      description: Authentication token passed as a query parameter.
    tokenHeader:
      type: apiKey
      in: header
      name: Authorization
      description: Authentication token passed in the Authorization header as 'token <token_value>'.