JupyterHub

Base URL: /hub/api, Version: 1.5.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	POST	Request a new API token
/authorizations/token/{token}	GET	Identify a user or service 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
/groups/{name}/users	POST	Add users to a group
/info	GET	Get detailed info about JupyterHub
/oauth2/authorize	GET	OAuth 2.0 authorize endpoint
/oauth2/token	POST	Request an OAuth2 token
/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
/user	GET	Return authenticated user's model
/users	GET	List users
/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}/activity	POST	Notify Hub of activity for a given user.
/users/{name}/server	DELETE	Stop a user's server
/users/{name}/server	POST	Start a user's single-user notebook server
/users/{name}/servers/{server_name}	DELETE	Stop a user's named-server
/users/{name}/servers/{server_name}	POST	Start a user's single-user named-server notebook server
/users/{name}/tokens	GET	List tokens for the user
/users/{name}/tokens	POST	Create a new token for the user
/users/{name}/tokens/{token_id}	DELETE	Delete (revoke) a token by id
/users/{name}/tokens/{token_id}	GET	Get the model for a token by id

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 a cookie

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

Used by single-user notebook servers to hand off cookie authentication to the Hub


cookie_name		path	string
cookie_value		path	string

Uses default content-types: application/json

200 OK: The user identified by the cookie

User
404 Not Found: A user is not found.

Request a new API token

POST /authorizations/token

Request a new API token to use with the JupyterHub REST API. If not already authenticated, username and password can be sent in the JSON request body. Logging in via this method is only available when the active Authenticator accepts passwords (e.g. not OAuth).

Uses default content-types: application/json

username: string
password: string

Uses default content-types: application/json

200 OK

The new API token

token: string: The new API token.

403 Forbidden

The user can not be authenticated.

Identify a user or service from an API token

GET /authorizations/token/{token}


token		path	string

Uses default content-types: application/json

200 OK: The user or service identified by the API token
404 Not Found: A user or service is not found.

List groups

GET /groups

Uses default content-types: application/json

200 OK: The list of groups

Group

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

Group

Create a group

POST /groups/{name}


name	group name	path	string

Uses default content-types: application/json

201 Created: The group has been created

Group

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

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

OAuth 2.0 authorize endpoint

GET /oauth2/authorize

Redirect users to this URL to begin the OAuth process. It is not an API endpoint.


client_id	The client id	query	string
response_type	The response type (always 'code')	query	string
state	A state string	query	string
redirect_uri	The redirect url	query	string

Uses default content-types: application/json

200 OK: Success
400 Bad Request: OAuth2Error

Request an OAuth2 token

POST /oauth2/token

Request an OAuth2 token from an authorization code. This request completes the OAuth process.

application/x-www-form-urlencoded


client_id	The client id	formData	string
client_secret	The client secret	formData	string
grant_type	The grant type (always 'authorization_code')	formData	string
code	The code provided by the authorization redirect	formData	string
redirect_uri	The redirect url	formData	string

Uses default content-types: application/json

200 OK

JSON response including the token

access_token: string: The new API token for the user
token_type: string: Will always be 'Bearer'

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

Service

Get a service by name

GET /services/{name}


name	service name	path	string

Uses default content-types: application/json

200 OK: The Service model

Service

Shutdown the Hub

POST /shutdown

Uses default content-types: application/json

proxy: boolean: Whether the proxy should be shutdown as well (default from Hub config)
servers: boolean: Whether users' notebook servers should be shutdown as well (default from Hub config)

Uses default content-types: application/json

202 Accepted: Shutdown successful
400 Bad Request: Unexpeced value for proxy or servers

Return authenticated user's model

GET /user

Uses default content-types: application/json

200 OK: The authenticated user's model is returned.

User

List users

GET /users


state	Return only users who have servers in the given state. If unspecified, return all users. active: all users with any active servers (ready OR pending) ready: all users who have any ready servers (running, not pending) inactive: all users who have no active servers (complement of active) Added in JupyterHub 1.3	query	string , x ∈ { inactive , active , ready }

state

Return only users who have servers in the given state. If unspecified, return all users.

active: all users with any active servers (ready OR pending) ready: all users who have any ready servers (running, not pending) inactive: all users who have no active servers (complement of active)

Added in JupyterHub 1.3

query

string , x ∈ { inactive , active , ready }

Uses default content-types: application/json

200 OK: The Hub's user list

User

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

User

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

User

Create a single user

POST /users/{name}


name	username	path	string

Uses default content-types: application/json

201 Created: The user has been created

User

Notify Hub of activity for a given user.

POST /users/{name}/activity

Notify the Hub of activity by the user, e.g. accessing a service or (more likely) actively using a server.

Uses default content-types: application/json

{
    "last_activity": "2019-02-06T12:54:14Z",
    "servers": {
        "": {
            "last_activity": "2019-02-06T12:54:14Z"
        },
        "gpu": {
            "last_activity": "2019-02-06T12:54:14Z"
        }
    }
}

last_activity: string (date-time)

Timestamp of last-seen activity for this user. Only needed if this is not activity associated with using a given server.

servers: object

Register activity for specific servers by name. The keys of this dict are the names of servers. The default server has an empty name ('').

<server name>: object

Activity for a single server.

last_activity: string (date-time): Timestamp of last-seen activity on this server.


name	username	path	string

Uses default content-types: application/json

401 Unauthorized #/responses/Unauthorized: Authentication/Authorization error
404 Not Found: No such user

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

Uses default content-types: application/json

Spawn options can be passed as a JSON body when spawning via the API instead of spawn form. The structure of the options will depend on the Spawner's configuration. The body itself will be available as user_options for the Spawner.


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

Stop a user's named-server

DELETE /users/{name}/servers/{server_name}

Uses default content-types: application/json

remove: boolean: Whether to fully remove the server, rather than just stop it. Removing a server deletes things like the state of the stopped server. Default: false.


name	username	path	string
server_name	name given to a named-server	path	string

Uses default content-types: application/json

202 Accepted: The user's notebook named-server has not yet stopped as it is taking a while to stop
204 No Content: The user's notebook named-server has stopped

Start a user's single-user named-server notebook server

POST /users/{name}/servers/{server_name}

Uses default content-types: application/json

Spawn options can be passed as a JSON body when spawning via the API instead of spawn form. The structure of the options will depend on the Spawner's configuration.

name

username

path

string

server_name

name given to a named-server.

Note that depending on your JupyterHub infrastructure there are chracterter size limitation to server_name. Default spawner with K8s pod will not allow Jupyter Notebooks to be spawned with a name that contains more than 253 characters (keep in mind that the pod will be spawned with extra characters to identify the user and hub).

path

string

Uses default content-types: application/json

201 Created: The user's notebook named-server has started
202 Accepted: The user's notebook named-server has not yet started, but has been requested

List tokens for the user

GET /users/{name}/tokens


name	username	path	string

Uses default content-types: application/json

200 OK: The list of tokens

Token
401 Unauthorized #/responses/Unauthorized: Authentication/Authorization error
404 Not Found: No such user

Create a new token for the user

POST /users/{name}/tokens

Uses default content-types: application/json

expires_in: number: lifetime (in seconds) after which the requested token will expire.
note: string: A note attached to the token for future bookkeeping


name	username	path	string

Uses default content-types: application/json

201 Created: The newly created token

Token
400 Bad Request: Body must be a JSON dict or empty

Delete (revoke) a token by id

DELETE /users/{name}/tokens/{token_id}


name	username	path	string
token_id		path	string

Uses default content-types: application/json

204 No Content: The token has been deleted

Get the model for a token by id

GET /users/{name}/tokens/{token_id}


name	username	path	string
token_id		path	string

Uses default content-types: application/json

200 OK: The info for the new token

Token

Response definitions

NotFound: The specified resource was not found
Unauthorized: Authentication/Authorization error

Schema definitions

Group: object

name: string: The group's name
users: string[]: The names of users who are members of this group

string

Server: object

name: string: The server's name. The user's default server has an empty name ('')
ready: boolean: Whether the server is ready for traffic. Will always be false when any transition is pending.
pending: string , x ∈ { spawn , stop , }: The currently pending action, if any. A server is not ready if an action is pending.
url: string: The URL where the server can be accessed (typically /user/:name/:server.name/).
progress_url: string: The URL for an event-stream to retrieve events during a spawn.
started: string (date-time): UTC timestamp when the server was last started.
last_activity: string (date-time): UTC timestamp last-seen activity on this server.
state: object: Arbitrary internal state from this server's spawner. Only available on the hub's users list or get-user-by-name method, and only if a hub admin. None otherwise.
user_options: object: User specified options for the user's spawned instance of a single-user server.

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
info: object: Additional information a deployment can attach to a service. JupyterHub does not use this field.

Token: object

token: string: The token itself. Only present in responses to requests for a new token.
id: string: The id of the API token. Used for modifying or deleting the token.
user: string: The user that owns a token (undefined if owned by a service)
service: string: The service that owns the token (undefined if owned by a user)
note: string: A note about the token, typically describing what it was created for.
created: string (date-time): Timestamp when this token was created
expires_at: string (date-time): Timestamp when this token expires. Null if there is no expiry.
last_activity: string (date-time): Timestamp of last-seen activity using this token. Can be null if token has never been used.

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
servers: object[]: The active servers for this user.

Server