JupyterHub

Base URL: /hub/api, Version: 0.7.0

The REST API for JupyterHub

Default request content-types: application/json
Default response content-types: application/json
Schemes: http,https

Summary

Path Operation Description
/ GET

Get JupyterHub version

/authorizations/cookie/{cookie_name}/{cookie_value} GET

Identify a user from a cookie

/authorizations/token/{token} GET

Identify a user from an API token

/groups GET

List groups

/groups/{name} DELETE

Delete a group

GET

Get a group by name

POST

Create a group

/groups/{name}/users DELETE

Remove users from a group

POST

Add users to a group

/info GET

Get detailed info about JupyterHub

/proxy GET

Get the proxy's routing table

PATCH

Notify the Hub about a new proxy

POST

Force the Hub to sync with the proxy

/services GET

List services

/services/{name} GET

Get a service by name

/shutdown POST

Shutdown the Hub

/users GET

List users

POST

Create multiple users

/users/{name} DELETE

Delete a user

GET

Get a user by name

PATCH

Modify a user

POST

Create a single user

/users/{name}/admin-access POST

Grant admin access to this user's notebook server

/users/{name}/server DELETE

Stop a user's server

POST

Start a user's single-user notebook server

Security

token

Type: apiKey
Name:

Authorization

In:

header

Paths

Get JupyterHub version

GET /

This endpoint is not authenticated for the purpose of clients and user to identify the JupyterHub version before setting up authentication.

Uses default content-types: application/json

200 OK

The JupyterHub version

version: string

The version of JupyterHub itself

Identify a user from an API token

GET /authorizations/token/{token}

token path string

Uses default content-types: application/json

200 OK

The user identified by the API token

List groups

GET /groups

Uses default content-types: application/json

200 OK

The list of groups

Delete a group

DELETE /groups/{name}

name

group name

path string

Uses default content-types: application/json

204 No Content

The group has been deleted

Get a group by name

GET /groups/{name}

name

group name

path string

Uses default content-types: application/json

200 OK

The group model

Create a group

POST /groups/{name}

name

group name

path string

Uses default content-types: application/json

201 Created

The group has been created

Remove users from a group

DELETE /groups/{name}/users

Uses default content-types: application/json

The users to remove from the group

users: string[]

List of usernames to remove from the group

string
name

group name

path string

Uses default content-types: application/json

200 OK

The users have been removed from the group

Add users to a group

POST /groups/{name}/users

Uses default content-types: application/json

The users to add to the group

users: string[]

List of usernames to add to the group

string
name

group name

path string

Uses default content-types: application/json

200 OK

The users have been added to the group

Get detailed info about JupyterHub

GET /info

Detailed JupyterHub information, including Python version, JupyterHub's version and executable path, and which Authenticator and Spawner are active.

Uses default content-types: application/json

200 OK

Detailed JupyterHub info

version: string

The version of JupyterHub itself

python: string

The Python version, as returned by sys.version

sys_executable: string

The path to sys.executable running JupyterHub

authenticator: object
class: string

The Python class currently active for JupyterHub Authentication

version: string

The version of the currently active Authenticator

spawner: object
class: string

The Python class currently active for spawning single-user notebook servers

version: string

The version of the currently active Spawner

Get the proxy's routing table

GET /proxy

A convenience alias for getting the routing table directly from the proxy

Uses default content-types: application/json

200 OK

Routing table

configurable-http-proxy routing table (see configurable-http-proxy docs for details)

Notify the Hub about a new proxy

PATCH /proxy

Notifies the Hub of a new proxy to use.

Uses default content-types: application/json

Any values that have changed for the new proxy. All keys are optional.

ip: string

IP address of the new proxy

port: string

Port of the new proxy

protocol: string

Protocol of new proxy, if changed

auth_token: string

CONFIGPROXY_AUTH_TOKEN for the new proxy

Uses default content-types: application/json

200 OK

Success

Force the Hub to sync with the proxy

POST /proxy

Uses default content-types: application/json

200 OK

Success

List services

GET /services

Uses default content-types: application/json

200 OK

The service list

Get a service by name

GET /services/{name}

name

service name

path string

Uses default content-types: application/json

200 OK

The Service model

Shutdown the Hub

POST /shutdown

Uses default content-types: application/json

Whether users's notebook servers should be shutdown as well (default from Hub config)

Uses default content-types: application/json

200 OK

Hub has shutdown

List users

GET /users

Uses default content-types: application/json

200 OK

The Hub's user list

Create multiple users

POST /users

Uses default content-types: application/json

usernames: string[]

list of usernames to create on the Hub

string
admin: boolean

whether the created users should be admins

Uses default content-types: application/json

201 Created

The users have been created

The created users

User
Delete a user

DELETE /users/{name}

name

username

path string

Uses default content-types: application/json

204 No Content

The user has been deleted

Get a user by name

GET /users/{name}

name

username

path string

Uses default content-types: application/json

200 OK

The User model

Modify a user

PATCH /users/{name}

Change a user's name or admin status

Uses default content-types: application/json

Updated user info. At least one key to be updated (name or admin) is required.

name: string

the new name (optional, if another key is updated i.e. admin)

admin: boolean

update admin (optional, if another key is updated i.e. name)

name

username

path string

Uses default content-types: application/json

200 OK

The updated user info

Create a single user

POST /users/{name}

name

username

path string

Uses default content-types: application/json

201 Created

The user has been created

Grant admin access to this user's notebook server

POST /users/{name}/admin-access

name

username

path string

Uses default content-types: application/json

200 OK

Sets a cookie granting the requesting administrator access to the user's notebook server

Stop a user's server

DELETE /users/{name}/server

name

username

path string

Uses default content-types: application/json

202 Accepted

The user's notebook server has not yet stopped as it is taking a while to stop

204 No Content

The user's notebook server has stopped

Start a user's single-user notebook server

POST /users/{name}/server

name

username

path string

Uses default content-types: application/json

201 Created

The user's notebook server has started

202 Accepted

The user's notebook server has not yet started, but has been requested

Schema definitions

Group: object

name: string

The group's name

users: string[]

The names of users who are members of this group

string

Service: object

name: string

The service's name

admin: boolean

Whether the service is an admin

url: string

The internal url where the service is running

prefix: string

The proxied URL prefix to the service's url

pid: number

The PID of the service process (if managed)

command: string[]

The command used to start the service (if managed)

string

User: object

name: string

The user's name

admin: boolean

Whether the user is an admin

groups: string[]

The names of groups where this user is a member

string
server: string

The user's notebook server's base URL, if running; null if not.

pending: string , x ∈ { spawn , stop }

The currently pending action, if any

last_activity: string (date-time)

Timestamp of last-seen activity from the user