openapi: 3.0.3
info:
  title: 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.
  version: '7.0'
  contact:
    name: Project Jupyter
    url: https://jupyter.org
  license:
    name: BSD-3-Clause
    url: https://github.com/jupyter/notebook/blob/main/LICENSE
servers:
  - url: http://localhost:8888/api
    description: Local Jupyter Notebook server
tags:
  - name: Contents
    description: Notebook and file contents.
  - name: Kernels
    description: Running kernels.
  - name: KernelSpecs
    description: Available kernel specs.
  - name: Sessions
    description: Notebook sessions.
  - name: Terminals
    description: Terminal sessions.
paths:
  /contents/{path}:
    parameters:
      - in: path
        name: path
        required: true
        schema:
          type: string
    get:
      tags: [Contents]
      summary: Get contents at a path
      operationId: getContents
      parameters:
        - in: query
          name: type
          schema:
            type: string
            enum: [directory, file, notebook]
        - in: query
          name: format
          schema:
            type: string
            enum: [text, base64, json]
        - in: query
          name: content
          schema:
            type: integer
            enum: [0, 1]
      responses:
        '200':
          description: Contents at the path.
    put:
      tags: [Contents]
      summary: Save or upload contents at a path
      operationId: saveContents
      responses:
        '200':
          description: Contents saved.
        '201':
          description: Contents created.
    patch:
      tags: [Contents]
      summary: Rename or move contents
      operationId: renameContents
      responses:
        '200':
          description: Contents renamed.
    post:
      tags: [Contents]
      summary: Create a new file or directory
      operationId: createContents
      responses:
        '201':
          description: Contents created.
    delete:
      tags: [Contents]
      summary: Delete contents at a path
      operationId: deleteContents
      responses:
        '204':
          description: Contents deleted.
  /contents/{path}/checkpoints:
    parameters:
      - in: path
        name: path
        required: true
        schema:
          type: string
    get:
      tags: [Contents]
      summary: List checkpoints for a file
      operationId: listCheckpoints
      responses:
        '200':
          description: List of checkpoints.
    post:
      tags: [Contents]
      summary: Create a new checkpoint
      operationId: createCheckpoint
      responses:
        '201':
          description: Checkpoint created.
  /contents/{path}/checkpoints/{checkpoint_id}:
    parameters:
      - in: path
        name: path
        required: true
        schema:
          type: string
      - in: path
        name: checkpoint_id
        required: true
        schema:
          type: string
    post:
      tags: [Contents]
      summary: Restore a file to a checkpoint
      operationId: restoreCheckpoint
      responses:
        '204':
          description: Checkpoint restored.
    delete:
      tags: [Contents]
      summary: Delete a checkpoint
      operationId: deleteCheckpoint
      responses:
        '204':
          description: Checkpoint deleted.
  /kernels:
    get:
      tags: [Kernels]
      summary: List running kernels
      operationId: listKernels
      responses:
        '200':
          description: List of running kernels.
    post:
      tags: [Kernels]
      summary: Start a new kernel
      operationId: startKernel
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                path:
                  type: string
      responses:
        '201':
          description: Kernel started.
  /kernels/{kernel_id}:
    parameters:
      - in: path
        name: kernel_id
        required: true
        schema:
          type: string
    get:
      tags: [Kernels]
      summary: Get kernel info
      operationId: getKernel
      responses:
        '200':
          description: Kernel details.
    delete:
      tags: [Kernels]
      summary: Shut down a kernel
      operationId: shutdownKernel
      responses:
        '204':
          description: Kernel shut down.
  /kernels/{kernel_id}/interrupt:
    parameters:
      - in: path
        name: kernel_id
        required: true
        schema:
          type: string
    post:
      tags: [Kernels]
      summary: Interrupt a kernel
      operationId: interruptKernel
      responses:
        '204':
          description: Kernel interrupted.
  /kernels/{kernel_id}/restart:
    parameters:
      - in: path
        name: kernel_id
        required: true
        schema:
          type: string
    post:
      tags: [Kernels]
      summary: Restart a kernel
      operationId: restartKernel
      responses:
        '200':
          description: Kernel restarted.
  /kernelspecs:
    get:
      tags: [KernelSpecs]
      summary: List installed kernel specs
      operationId: listKernelSpecs
      responses:
        '200':
          description: Available kernel specs and the default kernel name.
  /sessions:
    get:
      tags: [Sessions]
      summary: List active sessions
      operationId: listSessions
      responses:
        '200':
          description: List of active sessions.
    post:
      tags: [Sessions]
      summary: Create a new session
      operationId: createSession
      responses:
        '201':
          description: Session created.
  /sessions/{session_id}:
    parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
    get:
      tags: [Sessions]
      summary: Get a session
      operationId: getSession
      responses:
        '200':
          description: Session details.
    patch:
      tags: [Sessions]
      summary: Update a session
      operationId: updateSession
      responses:
        '200':
          description: Session updated.
    delete:
      tags: [Sessions]
      summary: Delete a session
      operationId: deleteSession
      responses:
        '204':
          description: Session deleted.
  /terminals:
    get:
      tags: [Terminals]
      summary: List active terminals
      operationId: listTerminals
      responses:
        '200':
          description: List of active terminals.
    post:
      tags: [Terminals]
      summary: Start a new terminal
      operationId: startTerminal
      responses:
        '201':
          description: Terminal started.
  /terminals/{terminal_id}:
    parameters:
      - in: path
        name: terminal_id
        required: true
        schema:
          type: string
    get:
      tags: [Terminals]
      summary: Get a terminal
      operationId: getTerminal
      responses:
        '200':
          description: Terminal details.
    delete:
      tags: [Terminals]
      summary: Stop a terminal
      operationId: stopTerminal
      responses:
        '204':
          description: Terminal stopped.
components:
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      bearerFormat: Jupyter-Token