The REST API

An interactive version is available here.

GET /api/contents/{path}

Get contents of file or directory

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.

Parameters
  • path (string) – file path

Query Parameters
  • type (string) – File type (‘file’, ‘directory’)

  • format (string) – How file content should be returned (‘text’, ‘base64’)

  • content (integer) – Return content (0 for no content, 1 for return content)

Status Codes
Response Headers
  • Last-Modified – Last modified date for file

Response JSON Object
  • content (string) – The content, if requested (otherwise null). Will be an array if type is ‘directory’ (required)

  • created (string) – Creation timestamp (required)

  • format (string) – Format of content (one of null, ‘text’, ‘base64’, ‘json’) (required)

  • last_modified (string) – Last modified timestamp (required)

  • mimetype (string) – 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. (required)

  • name (string) – Name of file or directory, equivalent to the last part of the path (required)

  • path (string) – Full path for file or directory (required)

  • size (integer) – The size of the file or notebook in bytes. If no size is provided, defaults to null.

  • type (string) – Type of content (required)

  • writable (boolean) – indicates whether the requester has permission to edit the file (required)

POST /api/contents/{path}

Create a new file in the specified path

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.

Parameters
  • path (string) – file path

Request JSON Object
  • copy_from (string) –

  • ext (string) –

  • type (string) –

Status Codes
Response Headers
  • Location – URL for the new file

Response JSON Object
  • content (string) – The content, if requested (otherwise null). Will be an array if type is ‘directory’ (required)

  • created (string) – Creation timestamp (required)

  • format (string) – Format of content (one of null, ‘text’, ‘base64’, ‘json’) (required)

  • last_modified (string) – Last modified timestamp (required)

  • mimetype (string) – 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. (required)

  • name (string) – Name of file or directory, equivalent to the last part of the path (required)

  • path (string) – Full path for file or directory (required)

  • size (integer) – The size of the file or notebook in bytes. If no size is provided, defaults to null.

  • type (string) – Type of content (required)

  • writable (boolean) – indicates whether the requester has permission to edit the file (required)

PATCH /api/contents/{path}

Rename a file or directory without re-uploading content

Parameters
  • path (string) – file path

Request JSON Object
  • path (string) – New path for file or directory

Status Codes
Response Headers
  • Location – Updated URL for the file or directory

Response JSON Object
  • content (string) – The content, if requested (otherwise null). Will be an array if type is ‘directory’ (required)

  • created (string) – Creation timestamp (required)

  • format (string) – Format of content (one of null, ‘text’, ‘base64’, ‘json’) (required)

  • last_modified (string) – Last modified timestamp (required)

  • mimetype (string) – 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. (required)

  • name (string) – Name of file or directory, equivalent to the last part of the path (required)

  • path (string) – Full path for file or directory (required)

  • size (integer) – The size of the file or notebook in bytes. If no size is provided, defaults to null.

  • type (string) – Type of content (required)

  • writable (boolean) – indicates whether the requester has permission to edit the file (required)

PUT /api/contents/{path}

Save or upload file.

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.

Parameters
  • path (string) – file path

Request JSON Object
  • content (string) – The actual body of the document excluding directory type

  • format (string) – File format (‘json’, ‘text’, ‘base64’)

  • name (string) – The new filename if changed

  • path (string) – New path for file or directory

  • type (string) – Path dtype (‘notebook’, ‘file’, ‘directory’)

Status Codes
Response Headers
  • Location – Updated URL for the file or directory

  • Location – URL for the file or directory

Response JSON Object
  • content (string) – The content, if requested (otherwise null). Will be an array if type is ‘directory’ (required)

  • created (string) – Creation timestamp (required)

  • format (string) – Format of content (one of null, ‘text’, ‘base64’, ‘json’) (required)

  • last_modified (string) – Last modified timestamp (required)

  • mimetype (string) – 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. (required)

  • name (string) – Name of file or directory, equivalent to the last part of the path (required)

  • path (string) – Full path for file or directory (required)

  • size (integer) – The size of the file or notebook in bytes. If no size is provided, defaults to null.

  • type (string) – Type of content (required)

  • writable (boolean) – indicates whether the requester has permission to edit the file (required)

  • content – The content, if requested (otherwise null). Will be an array if type is ‘directory’ (required)

  • created – Creation timestamp (required)

  • format – Format of content (one of null, ‘text’, ‘base64’, ‘json’) (required)

  • last_modified – Last modified timestamp (required)

  • mimetype – 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. (required)

  • name – Name of file or directory, equivalent to the last part of the path (required)

  • path – Full path for file or directory (required)

  • size – The size of the file or notebook in bytes. If no size is provided, defaults to null.

  • type – Type of content (required)

  • writable – indicates whether the requester has permission to edit the file (required)

DELETE /api/contents/{path}

Delete a file in the given path

Parameters
  • path (string) – file path

Status Codes
Response Headers
  • Location – URL for the removed file

GET /api/contents/{path}/checkpoints

Get a list of checkpoints for a file

List checkpoints for a given file. There will typically be zero or one results.

Parameters
  • path (string) – file path

Status Codes
Response JSON Object
  • [].id (string) – Unique id for the checkpoint. (required)

  • [].last_modified (string) – Last modified timestamp (required)

POST /api/contents/{path}/checkpoints

Create a new checkpoint for a file

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.

Parameters
  • path (string) – file path

Status Codes
Response Headers
  • Location – URL for the checkpoint

Response JSON Object
  • id (string) – Unique id for the checkpoint. (required)

  • last_modified (string) – Last modified timestamp (required)

POST /api/contents/{path}/checkpoints/{checkpoint_id}

Restore a file to a particular checkpointed state

Parameters
  • path (string) – file path

  • checkpoint_id (string) – Checkpoint id for a file

Status Codes
DELETE /api/contents/{path}/checkpoints/{checkpoint_id}

Delete a checkpoint

Parameters
  • path (string) – file path

  • checkpoint_id (string) – Checkpoint id for a file

Status Codes
GET /api/sessions/{session}

Get session

Parameters
  • session (string) – session uuid

Status Codes
Response JSON Object
  • id (string) –

  • kernel (any) – Kernel information

  • name (string) – name of the session

  • path (string) – path to the session

  • type (string) – session type

PATCH /api/sessions/{session}

This can be used to rename the session.

Parameters
  • session (string) – session uuid

Request JSON Object
  • id (string) –

  • kernel (any) – Kernel information

  • name (string) – name of the session

  • path (string) – path to the session

  • type (string) – session type

Status Codes
Response JSON Object
  • id (string) –

  • kernel (any) – Kernel information

  • name (string) – name of the session

  • path (string) – path to the session

  • type (string) – session type

DELETE /api/sessions/{session}

Delete a session

Parameters
  • session (string) – session uuid

Status Codes
  • 204 No Content – Session (and kernel) were deleted

  • 410 Gone – Kernel was deleted before the session, and the session was not deleted (TODO - check to make sure session wasn’t deleted)

GET /api/sessions

List available sessions

Status Codes
  • 200 OK – List of current sessions

Response JSON Object
  • [].id (string) –

  • [].kernel (any) – Kernel information

  • [].name (string) – name of the session

  • [].path (string) – path to the session

  • [].type (string) – session type

POST /api/sessions

Create a new session, or return an existing session if a session of the same name already exists

Request JSON Object
  • id (string) –

  • kernel (any) – Kernel information

  • name (string) – name of the session

  • path (string) – path to the session

  • type (string) – session type

Status Codes
Response Headers
  • Location – URL for session commands

Response JSON Object
  • id (string) –

  • kernel (any) – Kernel information

  • name (string) – name of the session

  • path (string) – path to the session

  • type (string) – session type

GET /api/kernels

List the JSON data for all kernels that are currently running

Status Codes
  • 200 OK – List of currently-running kernel uuids

Response JSON Object
  • [] (any) – Kernel information

POST /api/kernels

Start a kernel and return the uuid

Request JSON Object
  • name (string) – Kernel spec name (defaults to default kernel spec for server) (required)

  • path (string) – API path from root to the cwd of the kernel

Status Codes
Response Headers
  • Location – Model for started kernel

GET /api/kernels/{kernel_id}

Get kernel information

Parameters
  • kernel_id (string) – kernel uuid

Status Codes
  • 200 OK – Kernel information

DELETE /api/kernels/{kernel_id}

Kill a kernel and delete the kernel id

Parameters
  • kernel_id (string) – kernel uuid

Status Codes
POST /api/kernels/{kernel_id}/interrupt

Interrupt a kernel

Parameters
  • kernel_id (string) – kernel uuid

Status Codes
POST /api/kernels/{kernel_id}/restart

Restart a kernel

Parameters
  • kernel_id (string) – kernel uuid

Status Codes
Response Headers
  • Location – URL for kernel commands

GET /api/kernelspecs

Get kernel specs

Status Codes
Response JSON Object
  • default (string) – Default kernel name

  • kernelspecs (object) –

GET /api/config/{section_name}

Get a configuration section by name

Parameters
  • section_name (string) – Name of config section

Status Codes
  • 200 OK – Configuration object

PATCH /api/config/{section_name}

Update a configuration section by name

Parameters
  • section_name (string) – Name of config section

Status Codes
  • 200 OK – Configuration object

GET /api/terminals

Get available terminals

Status Codes
Response JSON Object
  • [].last_activity (string) – ISO 8601 timestamp for the last-seen activity on this terminal. Use this to identify which terminals have been inactive since a given time. Timestamps will be UTC, indicated ‘Z’ suffix.

  • [].name (string) – name of terminal (required)

POST /api/terminals

Create a new terminal

Status Codes
Response JSON Object
  • last_activity (string) – ISO 8601 timestamp for the last-seen activity on this terminal. Use this to identify which terminals have been inactive since a given time. Timestamps will be UTC, indicated ‘Z’ suffix.

  • name (string) – name of terminal (required)

GET /api/terminals/{terminal_id}

Get a terminal session corresponding to an id.

Parameters
  • terminal_id (string) – ID of terminal session

Status Codes
Response JSON Object
  • last_activity (string) – ISO 8601 timestamp for the last-seen activity on this terminal. Use this to identify which terminals have been inactive since a given time. Timestamps will be UTC, indicated ‘Z’ suffix.

  • name (string) – name of terminal (required)

DELETE /api/terminals/{terminal_id}

Delete a terminal session corresponding to an id.

Parameters
  • terminal_id (string) – ID of terminal session

Status Codes
GET /api/status

Get the current status/activity of the server.

Status Codes
  • 200 OK – The current status of the server

GET /api/spec.yaml

Get the current spec for the notebook server’s APIs.

Status Codes
  • 200 OK – The current spec for the notebook server’s APIs.