JupyterHub

Base URL: /hub/api, Version: 0.9.0dev

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

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

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

POST

Start a user's single-user notebook server

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

Stop a user's named-server

POST

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

/users/{name}/tokens GET

List tokens for the user

POST

Create a new token for the user

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

Delete (revoke) a token by 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

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

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

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

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

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.

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

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

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

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

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

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 of 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.