Notebooks Hub API

This section documents the functionality of Notebooks Hub API.

Notebooks Hub API is a Node.js application that provides a REST API for managing and interacting with the Notebooks Hub UI. It is built using the LoopBack framework. Notebooks Hub API controls external services, such as JupyterHub, Vault, and other similar services, through REST API calls. For more details on LoopBack, please refer to the LoopBack documentation

At the center on Notebooks Hub is the concept of Server - an application instance launched by JupyterHub and providing (i.e. JupyterLab, VSCode, etc). Notebooks Hub tracks useful metadata to the JupyterHub servers. For that end we use Templates - a set of metadata that describes a Server, which can be thought of as Server settings. Templates are used to create new Servers.

ServerData database model has the following properties:

  1. name - this is the server name that will be used in JupyterHub

  2. owner - the user under whose account the server will be created in JupyterHub

  3. templateData - templateData object used by this server

  4. status - one of the following: ‘stopped’, ‘starting’, ‘running’, ‘stopping’, based on the status of the server in JupyterHub

  5. _id - internal ID in the database

ServerController

Each Template may have multiple Servers associated with it (many-to-one relationship). This relationship is particularly important in the case of Featured and Quick Launch Templates as it enables users to quickly create and start multiple server instances based on the same configuration. This ensures consistency across environments and also provides scalability, as users can quickly deploy identical setups tailored to their needs without reconfiguring the Template each time.”

GET /admin/access/{type}/{id}

Admin-only get viewers and editors for a shareable artifact.

Parameters:

  • type (string)

  • id (string)

Status Codes:

  • 200 OK – Artifact access details

POST /admin/access/{type}/{id}/revoke

Admin-only revoke access for a shareable artifact.

Parameters:

  • type (string)

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
POST /admin/access/{type}/{id}/share

Admin-only share access for a shareable artifact.

Parameters:

  • type (string)

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
GET /admin/artifacts/by-user/{email}

List artifacts that belong to a user from Mongo metadata and OpenFGA tuples.

Parameters:

  • email (string)

Query Parameters:

  • maxTuples (number)

Status Codes:

  • 200 OK – Artifact ownership details by user

GET /admin/artifacts/lookup

Lookup artifact references by subject key (username, userId, groupId, orgId).

Query Parameters:

  • keyType (string)

  • key (string)

  • maxTuples (number)

Status Codes:

  • 200 OK – Artifact reference lookup details

GET /admin/db/objects

List Mongo metadata objects by object type, optionally filtered by user email.

Query Parameters:

  • type (string)

  • email (string)

  • limit (number)

Status Codes:

  • 200 OK – Mongo object results for selected type

GET /admin/fga/tuples/by-artifact/{artifactId}

Inspect all OpenFGA tuples that reference an artifact id as object or userset.

Parameters:

  • artifactId (string)

Query Parameters:

  • type (string)

  • maxTuples (number)

Status Codes:

  • 200 OK – Tuples referencing this artifact id

GET /admin/fga/tuples/by-type/{type}

List OpenFGA tuples where object and/or user userset matches a selected type.

Parameters:

  • type (string)

Query Parameters:

  • position (string)

  • relation (string)

  • maxTuples (number)

  • scanLimit (number)

Status Codes:

  • 200 OK – Tuple list filtered by type

DELETE /admin/fga/tuples/delete

Delete selected OpenFGA tuples by exact user/relation/object key.

Request JSON Object:

  • tuples[].object (string) – (required)

  • tuples[].relation (string) – (required)

  • tuples[].user (string) – (required)

Status Codes:

  • 200 OK – Tuple delete result

GET /admin/fga/tuples/orphans

Find OpenFGA tuples whose object/userset artifact references do not exist in Mongo metadata.

Query Parameters:

  • maxTuples (number)

Status Codes:

  • 200 OK – Potential orphan tuples

POST /auth/authorize

Create an authorization URL for the user

Status Codes:

  • 200 OK – Authorization URL created successfully

Response JSON Object:

  • authorizationUrl (string)

POST /auth/logout

Logout the user

Request JSON Object:

  • id_token (string) – (required)

Status Codes:

  • 200 OK – Logout successful

Response JSON Object:

  • logoutUrl (string)

POST /auth/refresh

Refresh an expired access token

Request JSON Object:

  • refresh_token (string) – (required)

Status Codes:
Response JSON Object:

  • access_token (string) – (required)

  • expires_at (number) – (required)

  • expires_in (number) – (required)

  • id_token (string) – (required)

  • refresh_token (string)

  • scope (string) – (required)

  • token_type (string) – (required)

POST /auth/token

Exchange the authorization code for an access token.

Request JSON Object:

  • code (string) – (required)

Status Codes:
Response JSON Object:

  • access_token (string) – (required)

  • expires_at (number) – (required)

  • expires_in (number) – (required)

  • id_token (string) – (required)

  • refresh_token (string)

  • scope (string) – (required)

  • token_type (string) – (required)

GET /authenticated

Verify the access to a protected route.

Status Codes:

  • 200 OK – Route is protected

GET /datasets

Get Datasets for a given user.

Status Codes:

  • 200 OK – An array of Datasets

Response JSON Object:

  • []._id (string)

  • [].description (string)

  • [].directory (string)

  • [].host (string)

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

  • [].owner (string)

  • [].parent (string)

  • [].port (string)

  • [].schema (string)

  • [].tables (string)

  • [].type (string)

  • [].url (string)

  • [].version (string) – (required)

  • [].write_access (boolean)

POST /datasets

Create a new Dataset

This creates an empty directory on the file system.

Request JSON Object:

  • description (string)

  • directory (string)

  • host (string)

  • name (string) – (required)

  • parent (string)

  • port (string)

  • schema (string)

  • tables (string)

  • type (string)

  • url (string)

  • version (string) – (required)

  • write_access (boolean)

Status Codes:
Response JSON Object:

  • _id (string)

  • description (string)

  • directory (string)

  • host (string)

  • name (string) – (required)

  • owner (string)

  • parent (string)

  • port (string)

  • schema (string)

  • tables (string)

  • type (string)

  • url (string)

  • version (string) – (required)

  • write_access (boolean)

GET /datasets/admin/by-user/{email}

Admin-only lookup of datasets owned by a specific user.

Parameters:

  • email (string)

Status Codes:

  • 200 OK – Datasets grouped by name for the selected owner

DELETE /datasets/{id}

Delete Dataset with given ID

Parameters:

  • id (string)

Status Codes:
PATCH /datasets/{id}

Update Dataset with given ID

Parameters:

  • id (string)

Request JSON Object:

  • description (string)

  • directory (string)

  • host (string)

  • name (string)

  • parent (string)

  • port (string)

  • schema (string)

  • tables (string)

  • type (string)

  • url (string)

  • version (string)

Status Codes:
GET /datasets/{id}/access

Get accessible users for a Dataset with a given ID and type

Parameters:

  • id (string)

Query Parameters:

  • type (string)

Status Codes:

  • 200 OK – An array of users with their access levels

Response JSON Object:

  • [].access (string)

  • [].entity (string)

POST /datasets/{id}/revoke

Revoke access to a Dataset with a given ID

Parameters:

  • id (string)

Request JSON Object:

  • groupArray (string)

  • orgArray (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
POST /datasets/{id}/share

Share a Dataset with a given ID

Parameters:

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
GET /groups

Get Groups accessible to the current user.

Status Codes:
Response JSON Object:

  • []._id (string)

  • [].description (string)

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

  • [].owner (string) – (required)

POST /groups

Create a new Group.

Request JSON Object:

  • description (string)

  • name (string) – (required)

Status Codes:

  • 200 OK – Group POST success.

Response JSON Object:

  • _id (string)

  • description (string)

  • name (string) – (required)

  • owner (string) – (required)

GET /groups/my-memberships

Get groups the current user is a member of (OpenFGA listObjects).

Status Codes:

  • 200 OK – Array of Groups the user is a member of.

Response JSON Object:

  • []._id (string)

  • [].description (string)

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

  • [].owner (string) – (required)

DELETE /groups/{id}

Delete a Group by ID.

Parameters:

  • id (string)

Status Codes:
GET /groups/{id}

Get a Group by ID.

Parameters:

  • id (string)

Status Codes:
Response JSON Object:

  • _id (string)

  • description (string)

  • name (string) – (required)

  • owner (string) – (required)

PATCH /groups/{id}

Update group metadata (name and/or description) by ID.

Parameters:

  • id (string)

Request JSON Object:

  • description (string)

  • name (string)

Status Codes:

  • 200 OK – Group PATCH success.

Response JSON Object:

  • _id (string)

  • description (string)

  • name (string) – (required)

  • owner (string) – (required)

POST /groups/{id}/leave

Leave a Group. Any authenticated member can remove themselves.

Parameters:

  • id (string)

Status Codes:
GET /groups/{id}/members

Get all members of a Group.

Parameters:

  • id (string)

Status Codes:

  • 200 OK – Array of Group members.

Response JSON Object:

  • [] (string)

POST /groups/{id}/members

Add a member to a Group.

Parameters:

  • id (string)

Query Parameters:

  • memberEmail (string)

Status Codes:

  • 200 OK – Group member added successfully.

DELETE /groups/{id}/members/{memberEmail}

Remove a member from a Group.

Parameters:

  • id (string)

  • memberEmail (string)

Status Codes:
GET /healthcheck

Get application health status.

Check for a working JupyterHub connection, mounted folders, and working database connection.

Query Parameters:

  • email (string)

Status Codes:

  • 200 OK – Health status returned

PUT /initialize

Initialize a new JupyterHub user and set up their environment.

Query Parameters:

  • email (string)

Status Codes:
GET /modules

Get Modules for a given user.

Status Codes:

  • 200 OK – An array of Modules

Response JSON Object:

  • []._id (string)

  • [].description (string)

  • [].featured (boolean)

  • [].luaModuleFile[].arguments[] (string)

  • [].luaModuleFile[].id (string)

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

  • [].owner (string)

  • [].version (string) – (required)

  • [].write_access (boolean)

POST /modules

Create a new Module

This creates an empty binaries and a Lmod modulefile on the file system.

Request JSON Object:

  • description (string)

  • featured (boolean)

  • luaModuleFile[].arguments[] (string)

  • luaModuleFile[].id (string)

  • name (string) – (required)

  • version (string) – (required)

  • write_access (boolean)

Status Codes:
Response JSON Object:

  • _id (string)

  • description (string)

  • featured (boolean)

  • luaModuleFile[].arguments[] (string)

  • luaModuleFile[].id (string)

  • name (string) – (required)

  • owner (string)

  • version (string) – (required)

  • write_access (boolean)

GET /modules/admin/by-user/{email}

Admin-only lookup of modules owned by a specific user.

Parameters:

  • email (string)

Status Codes:

  • 200 OK – Modules grouped by name for the selected owner

DELETE /modules/{id}

Delete a Module with given ID

Parameters:

  • id (string)

Status Codes:
PATCH /modules/{id}

Update Module with given ID

Parameters:

  • id (string)

Request JSON Object:

  • description (string)

  • luaModuleFile[].arguments[] (string)

  • luaModuleFile[].id (string)

  • name (string)

  • version (string)

Status Codes:
GET /modules/{id}/access

Get accessible users for a Module with a given ID and type

Parameters:

  • id (string)

Query Parameters:

  • type (string)

Status Codes:

  • 200 OK – An array of users with their access levels

Response JSON Object:

  • [].access (string)

  • [].entity (string)

POST /modules/{id}/revoke

Revoke access to a Module with a given ID

Parameters:

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
POST /modules/{id}/share

Share a Module with a given ID

Parameters:

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
GET /profile

Retrieve profile details for the logged in user, including hub admin status.

Status Codes:

  • 200 OK – Current user profile payload

Response JSON Object:

  • email (string) – (required)

  • isHubAdmin (boolean) – (required)

POST /secret/share/{id}

Share a Secret with a given ID

Parameters:

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
DELETE /secret/{id}

Delete a Secret with a given ID

Parameters:

  • id (string)

Status Codes:
GET /secret/{id}

Get Secret with a given ID

Parameters:

  • id (string)

Status Codes:
PATCH /secret/{id}

Update a Secret with a given ID

Parameters:

  • id (string)

Request JSON Object:

  • description (string)

  • mount_path (string)

  • secretName (string)

Status Codes:
POST /secret/{id}/revoke

Remove access to a Secret with a given ID

Parameters:

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
GET /secrets

Get Secrets. Optionally filter by owner, type and name

Query Parameters:

  • owner (string)

  • type (string)

  • name (string)

Status Codes:

  • 200 OK – An array of Secrets

Response JSON Object:

  • []._id (string)

  • [].description (string)

  • [].engine (string) – (required)

  • [].mount_path (string)

  • [].owner (string) – (required)

  • [].secretName (string) – (required)

  • [].secret_path (string) – path to Secret in Vault directory (required)

  • [].type (string) – (required)

POST /secrets

Create a new Secret.

Request JSON Object:

  • description (string)

  • mount_path (string)

  • secretName (string) – (required)

  • type (string) – (required)

Status Codes:

  • 200 OK – Secret POST success. Upload Secret Object.

GET /secrets/admin/by-user/{email}

Admin-only lookup of secrets owned by a specific user.

Parameters:

  • email (string)

Status Codes:

  • 200 OK – An array of owned secrets

Response JSON Object:

  • []._id (string)

  • [].description (string)

  • [].engine (string) – (required)

  • [].mount_path (string)

  • [].owner (string) – (required)

  • [].secretName (string) – (required)

  • [].secret_path (string) – path to Secret in Vault directory (required)

  • [].type (string) – (required)

GET /servers

Get Servers. Optionally filter by owner, type or name

Query Parameters:

  • owner (string)

  • type (string)

  • name (string)

Status Codes:

  • 200 OK – An array of Servers

Response JSON Object:

  • []._id (string)

  • [].owner (string) – (required)

  • [].status (string) – (required)

  • [].templateId (string) – (required)

POST /servers

Create a new Server and an associated Template.

Request JSON Object:

  • applicationType (string) – (required)

  • datasets[] (string)

  • description (string) – (required)

  • featuredImage (string)

  • filePath (string)

  • hardware (string) – (required)

  • modules[] (string)

  • name (string) – (required)

  • public (boolean) – (required)

  • secrets[] (string)

  • tags[] (string)

  • type (string) – (required)

Status Codes:
Response JSON Object:

  • _id (string)

  • owner (string) – (required)

  • status (string) – (required)

  • templateId (string) – (required)

PUT /servers

Create a new Server based on an existing Template.

Query Parameters:

  • templateId (string)

Status Codes:
Response JSON Object:

  • _id (string)

  • owner (string) – (required)

  • status (string) – (required)

  • templateId (string) – (required)

DELETE /servers/{id}

Delete a Server with given ID. If the Server is running, it will be stopped first. It also deletes the associated Template if there is a one-to-one relationship between Server and Template.

Parameters:

  • id (string)

Status Codes:
GET /servers/{id}

Get Server with a given ID

Parameters:

  • id (string)

Status Codes:
Response JSON Object:

  • []._id (string)

  • [].owner (string) – (required)

  • [].status (string) – (required)

  • [].templateId (string) – (required)

GET /servers/{id}/share

Share a Server with given ID

Parameters:

  • id (string)

Status Codes:

  • 200 OK – Server sharing details

PUT /servers/{id}/start

Start a Server with given ID

Parameters:

  • id (string)

Status Codes:
PUT /servers/{id}/stop

Stop a Server with given ID

Parameters:

  • id (string)

Status Codes:
DELETE /template

Delete a Template with a given ID

Query Parameters:

  • id (string)

Status Codes:
PATCH /template

Update Template with given id.

Query Parameters:

  • templateId (string)

Request JSON Object:

  • applicationType (string)

  • creator (string)

  • datasets[] (string)

  • description (string)

  • featuredImage (string)

  • filePath (string)

  • hardware (string)

  • modules[] (string)

  • name (string)

  • public (boolean)

  • secrets[] (string)

  • tags[] (string)

Status Codes:
POST /template

Create a new Template.

Request JSON Object:

  • applicationType (string) – (required)

  • datasets[] (string)

  • description (string) – (required)

  • featuredImage (string)

  • filePath (string)

  • hardware (string) – (required)

  • modules[] (string)

  • name (string) – (required)

  • public (boolean) – (required)

  • secrets[] (string)

  • tags[] (string)

  • type (string) – (required)

Status Codes:
Response JSON Object:

  • _id (string)

  • applicationType (string) – (required)

  • creator (string) – (required)

  • datasets[] (string)

  • description (string) – (required)

  • featuredImage (string)

  • filePath (string)

  • hardware (string) – (required)

  • modules[] (string)

  • name (string) – (required)

  • public (boolean) – (required)

  • secrets[] (string)

  • serverName (string) – (required)

  • tags[] (string)

  • timestamp (string)

  • type (string) – (required)

GET /template/{id}/access

Admin-only get template viewers and editors by subject type.

Parameters:

  • id (string)

Status Codes:

  • 200 OK – Template access details

POST /template/{id}/revoke

Admin-only revoke template access from users, groups, and orgs.

Parameters:

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
POST /template/{id}/share

Admin-only share template with users, groups, and orgs.

Parameters:

  • id (string)

Request JSON Object:

  • groupArray[] (string)

  • orgArray[] (string)

  • relation (string) – (required)

  • userArray[] (string)

Status Codes:
PATCH /template/{id}/type

Admin-only update of template type (e.g. quicklaunch/example).

Parameters:

  • id (string)

Request JSON Object:

  • type (string) – (required)

Status Codes:

  • 200 OK – Template type updated

Response JSON Object:

  • _id (string)

  • applicationType (string) – (required)

  • creator (string) – (required)

  • datasets[] (string)

  • description (string) – (required)

  • featuredImage (string)

  • filePath (string)

  • hardware (string) – (required)

  • modules[] (string)

  • name (string) – (required)

  • public (boolean) – (required)

  • secrets[] (string)

  • serverName (string) – (required)

  • tags[] (string)

  • timestamp (string)

  • type (string) – (required)

GET /templates

Get Templates. Optionally filter by type or email

Query Parameters:

  • type (string)

  • email (string)

Status Codes:

  • 200 OK – An array of Templates

Response JSON Object:

  • []._id (string)

  • [].applicationType (string) – (required)

  • [].creator (string) – (required)

  • [].datasets[] (string)

  • [].description (string) – (required)

  • [].featuredImage (string)

  • [].filePath (string)

  • [].hardware (string) – (required)

  • [].modules[] (string)

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

  • [].public (boolean) – (required)

  • [].secrets[] (string)

  • [].serverName (string) – (required)

  • [].tags[] (string)

  • [].timestamp (string)

  • [].type (string) – (required)

GET /templates/tags

Get Template tags sorted by frequency

Query Parameters:

  • type (string)

  • email (string)

Status Codes:

  • 200 OK – An array of sorted tag data

Response JSON Object:

  • []._id (string)

  • [].applicationType (string) – (required)

  • [].creator (string) – (required)

  • [].datasets[] (string)

  • [].description (string) – (required)

  • [].featuredImage (string)

  • [].filePath (string)

  • [].hardware (string) – (required)

  • [].modules[] (string)

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

  • [].public (boolean) – (required)

  • [].secrets[] (string)

  • [].serverName (string) – (required)

  • [].tags[] (string)

  • [].timestamp (string)

  • [].type (string) – (required)

GET /version

Get API version.

Status Codes:
POST /volume/file

Create a new file in a specified directory.

Request JSON Object:

  • content (string)

  • name (string)

  • path (string)

  • root (string)

  • type (string)

Status Codes:
Response JSON Object:

  • content (string)

  • name (string)

  • path (string)

  • root (string)

  • type (string)

GET /volume/files

Retrieve file data from a specified directory.

Query Parameters:

  • email (string)

  • root (string)

  • path (string)

Status Codes:

  • 200 OK – An array of file data

Response JSON Object:

  • [].name (string)

  • [].path (string)

  • [].root (string)

  • [].type (string)

GET /volume/hardware

Retrieve a list of hardware options.

Status Codes:

  • 200 OK – An array of hardware options

Response JSON Object:

  • [] (string)

GET /volume/lua

Retrieve a list of LUA file properties.

Status Codes:

  • 200 OK – An array of LUA file properties

Response JSON Object:

  • [] (string)

GET /whoami

Retrieve your username based on your JWT access token and session id.

Status Codes:

  • 200 OK – the logged in username