rest_api.yaml

swagger: '2.0'
info:
  title: Jupyter Notebook API
  description: Notebook API
  version: "4"
  contact:
    name: Jupyter Project
    url: jupyter.org
# will be prefixed to all paths
basePath: /api
produces:
  - application/json
consumes:
  - application/json
parameters:
  kernel:
    name: kernel
    required: true
    in: path
    description: kernel uuid
    type: string
    format: uuid
  session:
    name: session
    required: true
    in: path
    description: session uuid
    type: string
    format: uuid
  path:
    name: path
    required: true
    in: path
    description: file path
    type: string
  checkpoint_id:
    name: checkpoint_id
    required: true
    in: path
    description: Checkpoint id for a file
    type: string

paths:
  /contents/{path}:
    parameters:
      - $ref: '#/parameters/path'
    get:
      summary: Get contents of file or directory
      description: "A client can optionally specify a type and/or format argument via URL parameter. When given, the Contents service shall return a model in the requested type and/or format. If the request cannot be satisfied, e.g. type=text is requested, but the file is binary, then the request shall fail with 400 and have a JSON response containing a 'reason' field, with the value 'bad format' or 'bad type', depending on what was requested."
      tags:
        - contents
      parameters:
        - name: type
          in: query
          description: File type ('file', 'directory')
          type: string
          enum:
            - file
            - directory
        - name: format
          in: query
          description: "How file content should be returned ('text', 'base64')"
          type: string
          enum:
            - text
            - base64
        - name: content
          in: query
          description: "Return content (0 for no content, 1 for return content)"
          type: integer
      responses:
        404:
          description: No item found
        400:
          description: Bad request
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error condition
              reason:
                type: string
                description: Explanation of error reason
        200:
          description: Contents of file or directory
          headers:
            Last-Modified:
              description: Last modified date for file
              type: string
              format: dateTime
          schema:
            $ref: '#/definitions/Contents'
        500:
          description: Model key error
    post:
      summary: Create a new file in the specified path
      description: "A POST to /api/contents/path creates a New untitled, empty file or directory. A POST to /api/contents/path with body {'copy_from': '/path/to/OtherNotebook.ipynb'} creates a new copy of OtherNotebook in path."
      tags:
        - contents
      parameters:
        - name: model
          in: body
          description: Path of file to copy
          schema:
            type: object
            properties:
              copy_from:
                type: string
              ext:
                type: string
              type:
                type: string
      responses:
        201:
          description: File created
          headers:
            Location:
              description: URL for the new file
              type: string
              format: url
          schema:
            $ref: '#/definitions/Contents'
        404:
          description: No item found
        400:
          description: Bad request
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error condition
              reason:
                type: string
                description: Explanation of error reason
    patch:
      summary: Rename a file or directory without re-uploading content
      tags:
        - contents
      parameters:
        - name: path
          in: body
          required: true
          description: New path for file or directory.
          schema:
            type: object
            properties:
              path:
                type: string
                format: path
                description: New path for file or directory
      responses:
        200:
          description: Path updated
          headers:
            Location:
              description: Updated URL for the file or directory
              type: string
              format: url
          schema:
            $ref: '#/definitions/Contents'
        400:
          description: No data provided
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error condition
              reason:
                type: string
                description: Explanation of error reason
    put:
      summary: Save or upload file.
      description: "Saves the file in the location specified by name and path.  PUT is very similar to POST, but the requester specifies the name, whereas with POST, the server picks the name."
      tags:
        - contents
      parameters:
        - name: model
          in: body
          description: New path for file or directory
          schema:
            type: object
            properties:
              name:
                type: string
                description: The new filename if changed
              path:
                type: string
                description: New path for file or directory
              type:
                type: string
                description: Path dtype ('notebook', 'file', 'directory')
              format:
                type: string
                description: File format ('json', 'text', 'base64')
              content:
                type: string
                description: The actual body of the document excluding directory type
      responses:
        200:
          description: File saved
          headers:
            Location:
              description: Updated URL for the file or directory
              type: string
              format: url
          schema:
            $ref: '#/definitions/Contents'
        201:
          description: Path created
          headers:
            Location:
              description: URL for the file or directory
              type: string
              format: url
          schema:
            $ref: '#/definitions/Contents'
        400:
          description: No data provided
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error condition
              reason:
                type: string
                description: Explanation of error reason
    delete:
      summary: Delete a file in the given path
      tags:
        - contents
      responses:
        204:
          description: File deleted
          headers:
            Location:
              description: URL for the removed file
              type: string
              format: url
  /contents/{path}/checkpoints:
    parameters:
      - $ref: '#/parameters/path'
    get:
      summary: Get a list of checkpoints for a file
      description: List checkpoints for a given file. There will typically be zero or one results.
      tags:
        - contents
      responses:
        404:
          description: No item found
        400:
          description: Bad request
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error condition
              reason:
                type: string
                description: Explanation of error reason
        200:
          description: List of checkpoints for a file
          schema:
            type: array
            items:
              $ref: '#/definitions/Checkpoints'
        500:
          description: Model key error
    post:
      summary: Create a new checkpoint for a file
      description: "Create a new checkpoint with the current state of a file. With the default FileContentsManager, only one checkpoint is supported, so creating new checkpoints clobbers existing ones."
      tags:
        - contents
      responses:
        201:
          description: Checkpoint created
          headers:
            Location:
              description: URL for the checkpoint
              type: string
              format: url
          schema:
            $ref: '#/definitions/Checkpoints'
        404:
          description: No item found
        400:
          description: Bad request
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error condition
              reason:
                type: string
                description: Explanation of error reason
  /contents/{path}/checkpoints/{checkpoint_id}:
    post:
      summary: Restore a file to a particular checkpointed state
      tags:
        - contents
      responses:
        204:
          description: Checkpoint created
        400:
          description: Bad request
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error condition
              reason:
                type: string
                description: Explanation of error reason
    delete:
      summary: Delete a checkpoint
      tags:
        - contents
      responses:
        204:
          description: Checkpoint deleted
  /sessions/{session}:
    parameters:
      - $ref: '#/parameters/session'
    get:
      summary: Get session
      tags:
        - sessions
      responses:
        200:
          description: Session
          schema:
            $ref: '#/definitions/Session'
    patch:
      summary: "This can be used to rename the notebook, or move it to a new directory."
      tags:
        - sessions
      parameters:
        - name: model
          in: body
          required: true
          schema:
            type: object
            properties:
              notebook:
                type: object
                properties:
                  path:
                    type: string
                    format: path
                    description: new path for notebook
      responses:
        200:
          description: Session
          schema:
            $ref: '#/definitions/Session'
        400:
          description: No data provided
    delete:
      summary: Delete a session
      tags:
        - sessions
      responses:
        204:
          description: Session (and kernel) were deleted
        410:
          description: "Kernel was deleted before the session, and the session was *not* deleted (TODO - check to make sure session wasn't deleted)"
  /sessions:
    get:
      summary: List available sessions
      tags:
        - sessions
      responses:
        200:
          description: List of current sessions
          schema:
            type: array
            items:
              $ref: '#/definitions/Session'
    post:
      summary: "Create a new session, or return an existing session if a session for the notebook path already exists"
      tags:
        - sessions
      parameters:
        - name: session
          in: body
          schema:
            type: object
            properties:
              notebook:
                type: object
                required:
                  - path
                properties:
                  path:
                    type: string
                    description: path to notebook file
              kernel:
                type: object
                properties:
                  name:
                    type: string
                    description: "Kernel spec name, defaults to default kernel spec"
      responses:
        201:
          description: Session created or returned
          schema:
            $ref: '#/definitions/Session'
          headers:
            Location:
              description: URL for session commands
              type: string
              format: url
        501:
          description: Kernel not available
          schema:
            type: object
            description: error message
            properties:
              message:
                type: string
              short_message:
                type: string

  /kernels:
    get:
      summary: List the JSON data for all kernels that are currently running
      tags:
        - kernels
      responses:
        200:
          description: List of currently-running kernel uuids
          schema:
            type: array
            items:
              $ref: '#/definitions/Kernel'
    post:
      summary: Start a kernel and return the uuid
      tags:
        - kernels
      parameters:
        - name: name
          in: body
          description: Kernel spec name (defaults to default kernel spec for server)
          schema:
            type: object
            properties:
              name:
                type: string
      responses:
        201:
          description: Kernel started
          schema:
            $ref: '#/definitions/Kernel'
          headers:
            Location:
              description: Model for started kernel
              type: string
              format: url
  /kernels/{kernel_id}:
    parameters:
      - $ref: '#/parameters/kernel'
    get:
      summary: Get kernel information
      tags:
        - kernels
      responses:
        200:
          description: Kernel information
          schema:
            $ref: '#/definitions/Kernel'
    delete:
      summary: Kill a kernel and delete the kernel id
      tags:
        - kernels
      responses:
        204:
          description: Kernel deleted
  /kernels/{kernel_id}/interrupt:
    parameters:
      - $ref: '#/parameters/kernel'
    post:
      summary: Interrupt a kernel
      tags:
        - kernels
      responses:
        204:
          description: Kernel interrupted
  /kernels/{kernel_id}/restart:
    parameters:
      - $ref: '#/parameters/kernel'
    post:
      summary: Restart a kernel
      tags:
        - kernels
      responses:
        200:
          description: Kernel interrupted
          headers:
            Location:
              description: URL for kernel commands
              type: string
              format: url
          schema:
            $ref: '#/definitions/Kernel'

  /kernelspecs:
    get:
      summary: Get kernel specs
      tags:
        - kernelspecs
      responses:
        200:
          description: Kernel specs
          schema:
            type: object
            properties:
              default:
                type: string
                description: Default kernel name
              kernelspecs:
                type: object
                additionalProperties:
                  $ref: '#/definitions/KernelSpec'
  /config/{section_name}:
    get:
      summary: Get a configuration section by name
      tags:
        - config
      responses:
        200:
          description: Configuration object
          schema:
            type: object
    patch:
      summary: Update a configuration section by name
      tags:
        - config
      parameters:
        - name: configuration
          in: body
          schema:
            type: object
      responses:
        200:
          description: Configuration object
          schema:
            type: object

definitions:
  KernelSpec:
    description: Kernel spec (contents of kernel.json)
    properties:
      name:
        type: string
        description: Unique name for kernel
      spec:
        $ref: '#/definitions/KernelSpecFile'
        description: Kernel spec json file
      resources:
        type: object
        properties:
          kernel.js:
            type: string
            format: filename
            description: path for kernel.js file
          kernel.css:
            type: string
            format: filename
            description: path for kernel.css file
          logo-*:
            type: string
            format: filename
            description: path for logo file.  Logo filenames are of the form `logo-widthxheight`
  KernelSpecFile:
    description: Kernel spec json file
    required:
      - argv
      - display_name
      - language
    properties:
      language:
        type: string
        description: The programming language which this kernel runs. This will be stored in notebook metadata.
      argv:
        type: array
        description: "A list of command line arguments used to start the kernel. The text `{connection_file}` in any argument will be replaced with the path to the connection file."
        items:
          type: string
      display_name:
        type: string
        description: "The kernel's name as it should be displayed in the UI. Unlike the kernel name used in the API, this can contain arbitrary unicode characters."
      codemirror_mode:
        type: string
        description: Codemirror mode.  Can be a string *or* an valid Codemirror mode object.  This defaults to the string from the `language` property.
      env:
        type: object
        description: A dictionary of environment variables to set for the kernel. These will be added to the current environment variables.
        additionalProperties:
          type: string
      help_links:
        type: array
        description: Help items to be displayed in the help menu in the notebook UI.
        items:
          type: object
          required:
          - text
          - url
          properties:
            text:
              type: string
              description: menu item link text
            url:
              type: string
              format: URL
              description: menu item link url
  Kernel:
    description: Kernel information
    required:
      - id
      - name
    properties:
      id:
        type: string
        format: uuid
        description: uuid of kernel
      name:
        type: string
        description: kernel spec name
  Session:
    description: A session
    type: object
    properties:
      id:
        type: string
        format: uuid
      notebook:
        type: object
        properties:
          path:
            type: string
            description: path to notebook
      kernel:
        $ref: '#/definitions/Kernel'
  Contents:
    description: "A contents object.  The content and format keys may be null if content is not contained.  If type is 'file', then the mimetype will be null."
    type: object
    required:
      - type
      - name
      - path
      - writable
      - created
      - last_modified
      - mimetype
      - format
      - content
    properties:
      name:
        type: string
        description: "Name of file or directory, equivalent to the last part of the path"
      path:
        type: string
        description: Full path for file or directory
      type:
        type: string
        description: Type of content
        enum:
          - directory
          - file
          - notebook
      writable:
        type: boolean
        description: indicates whether the requester has permission to edit the file
      created:
        type: string
        description: Creation timestamp
        format: dateTime
      last_modified:
        type: string
        description: Last modified timestamp
        format: dateTime
      mimetype:
        type: string
        description: "The mimetype of a file.  If content is not null, and type is 'file', this will contain the mimetype of the file, otherwise this will be null."
      content:
        type: string
        description: "The content, if requested (otherwise null).  Will be an array if type is 'directory'"
      format:
        type: string
        description: Format of content (one of null, 'text', 'base64', 'json')
  Checkpoints:
    description: A checkpoint object.
    type: object
    required:
      - id
      - last_modified
    properties:
      id:
        type: string
        description: Unique id for the checkpoint.
      last_modified:
        type: string
        description: Last modified timestamp
        format: dateTime
  Config:
    description: A configuration object.
    type: object