Jupyter Notebooks Instance

Jupyter Notebooks

Jump to API response

Plotly allows the user to upload their Jupyter Notebooks to the Plotly Server. The notebooks appear in the user's profile, and can be shared with others just like Plotly Plots.

Reference

• authorization
• actions
  • upload
  • retrieve
  • html
  • update
  • partial update
  • trash
  • permanent delete
  • external

Authorization

Any user with or without a Plotly account may view public Jupyter Notebooks. For private files, see authentication.

Actions

upload

A Jupyter Notebook may be uploaded by making a POST request to the upload endpoint with the file contents as the request body:

POST https://api.plotly.com/v2/jupyter-notebooks/upload

The following options may be passed as HTTP headers to control the upload.

• X-File-Name: gives the filename of the Notebook being uploaded.

• Plotly-World-Readable: controls the visibility of the created notebook. May be true or false. Defaults to false.

• Plotly-Parent: gives the parent folder id.

• Plotly-Parent-Path: gives the path to the parent folder.

retrieve

A Single Notebook can be retrieved by a GET Request to the jupyter-notebooks endpoint.

Example:

// GET https://api.plotly.com/v2/jupyter-notebooks/username:123

html

The rendered HTML content of a notebook can be retrieved by a GET request to the jupyter-notebooks endpoint including html.

Example:

// GET https://api.plotly.com/v2/jupyter-notebooks/username:123/html

update

To completely replace the writable meta information of an existing notebook, you make a PUT request to the jupyter-notebooks endpoint and include the fid for the notebook.

Note, only the writable meta information may be updated. This includes filename,parent (or parent_path), world_readable, and content.

Note that parent_path may be specified in place of the parent field. Unlike parent, the parent_path field is not an integer id, but rather the complete path of the parent folder from your root folder (e.g., '/folder_nested_off_root/parent_folder/').

A successful PUT response will have a status code of 200 OK.

Example:

// PUT https://api.plotly.com/v2/jupyter-notebooks/bob:45 --> 200 OK
{
    "parent": -1,
    "world_readable": true,
    "filename": "my_new_filename",
}

partial update

To partially update an existing notebook, you make a PATCH request to the jupyter-notebooks endpoint and include the fid for the notebook.

Note, only the writable meta information may be updated. This includes filename, parent (or parent_path), world_readable, and content.

A successful PATCH response will have a status code of 200 OK.

Example:

// PATCH https://api.plotly.com/v2/jupyter-notebooks/bob:45 --> 200 OK
{
    "world_readable": true,
    "filename": "my_new_filename"
}

trash

This endpoint allows for the recoverable trashing of the notebook specified in the endpoint detail.

A successful trash response will have a status code of 200 OK.

Example:

// POST https://api.plotly.com/v2/jupyter-notebooks/plotlvr:9/trash ---> 200 OK

This request is idempotent. Trashing a notebook that is already trashed will also succeed and return 200 OK.

permanent_delete

This endpoint allows for the permanent deletion of the notebook specified in the endpoint detail.

A successful deletion response will have a status code of 204 No Content.

Example:

// DELETE https://api.plotly.com/v2/jupyter-notebooks/plotlvr:9/permanent_delete ---> 204 No Content

external

Given an external ?source url, this endpoint makes a GET request to retrieve notebook content. Upon success of the request, the content is parsed to enforce that the content is a valid jupyter notebook and the HTML content is returned.

The source must include the scheme (e.g., https) and must point to a resource that returns a jupyter notebook as its content directly; e.g., using /raw for github resources.

Example:

// GET https://api.plotly.com/v2/jupyter-notebooks/external?source=https%3A%2F%2Fgist.github.com%2Fbob%2Fc2e63539ea200ae0d8ee%2Fraw