openapi: 3.1.0
info:
title: JupyterHub REST API
description: |
The REST API for JupyterHub.
Return to JupyterHub documentation.
license:
name: BSD-3-Clause
identifier: BSD-3-Clause
version: 5.4.0.dev
servers:
- url: /hub/api
security:
- token: []
- oauth2: []
paths:
/:
get:
operationId: get-api
summary: Get JupyterHub version
description: |
This endpoint is not authenticated for the purpose of clients and user
to identify the JupyterHub version before setting up authentication.
responses:
200:
description: The JupyterHub version
content:
application/json:
schema:
type: object
properties:
version:
type: string
description: The version of JupyterHub itself
/info:
get:
operationId: get-info
summary: Get detailed info about JupyterHub
description: |
Detailed JupyterHub information, including Python version,
JupyterHub's version and executable path,
and which Authenticator and Spawner are active.
responses:
200:
description: Detailed JupyterHub info
content:
application/json:
schema:
type: object
properties:
version:
type: string
description: The version of JupyterHub itself
python:
type: string
description: The Python version, as returned by sys.version
sys_executable:
type: string
description: The path to sys.executable running JupyterHub
authenticator:
type: object
properties:
class:
type: string
description: The Python class currently active for
JupyterHub Authentication
version:
type: string
description: The version of the currently active
Authenticator
spawner:
type: object
properties:
class:
type: string
description: The Python class currently active for
spawning single-user notebook servers
version:
type: string
description: The version of the currently active Spawner
security:
- oauth2:
- read:hub
/user:
get:
operationId: get-current-user
summary: Get current user
description: |
Returns the User model for the owner of the authenticating token.
Includes information about the requesting token itself,
such as the currently authorized scopes.
responses:
200:
description: |
The authenticated user or service's model is returned
with additional information about the permissions associated with the request token.
content:
application/json:
schema:
$ref: "#/components/schemas/RequestIdentity"
security:
- oauth2: []
/users:
get:
operationId: get-users
summary: List users
parameters:
- name: state
in: query
description: |
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
schema:
type: string
enum:
- inactive
- active
- ready
- $ref: "#/components/parameters/paginationOffset"
- $ref: "#/components/parameters/paginationLimit"
- name: include_stopped_servers
in: query
description: |
Include stopped servers in user model(s).
Added in JupyterHub 3.0.
Allows retrieval of information about stopped servers,
such as activity and state fields.
schema:
type: boolean
allowEmptyValue: true
- name: sort
in: query
description: |
Sort users by this key (new in JupyterHub 5.0).
Default: `id` (opaque but stable internal order).
Supported fields: `id`, `name`, `last_activity`.
Results will be in ascending order.
Descending order can be requested with a `-` prefix,
e.g. `sort=-last_activity` for most recently active users first.
schema:
type: string
examples:
default:
value: id
summary: |
default: sort by internal id
by_name:
value: name
summary: |
sort by user.name
recent_activity:
value: "-last_activity"
summary: |
sort by last activity, most recent first
responses:
200:
description: The Hub's user list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/User"
security:
- oauth2:
- list:users
post:
operationId: post-users
summary: Create multiple users
requestBody:
content:
application/json:
schema:
type: object
properties:
usernames:
type: array
description: list of usernames to create on the Hub
items:
type: string
admin:
type: boolean
description: whether the created users should be admins
required: true
responses:
201:
description: The users have been created
content:
application/json:
schema:
type: array
description: The created users
items:
$ref: "#/components/schemas/User"
security:
- oauth2:
- admin:users
/users/{name}:
get:
operationId: get-user
summary: Get a user by name
parameters:
- $ref: "#/components/parameters/userName"
- name: include_stopped_servers
in: query
description: Include stopped servers in user model(s).
schema:
type: boolean
allowEmptyValue: true
responses:
200:
description: The User model
content:
application/json:
schema:
$ref: "#/components/schemas/User"
security:
- oauth2:
- read:users
post:
operationId: post-user
summary: Create a single user
parameters:
- $ref: "#/components/parameters/userName"
responses:
201:
description: The user has been created
content:
application/json:
schema:
$ref: "#/components/schemas/User"
security:
- oauth2:
- admin:users
delete:
operationId: delete-user
summary: Delete a user
parameters:
- $ref: "#/components/parameters/userName"
responses:
204:
description: The user has been deleted
content: {}
security:
- oauth2:
- delete:users
patch:
operationId: patch-user
summary: Modify a user
description: Change a user's name or admin status
parameters:
- $ref: "#/components/parameters/userName"
requestBody:
description: Updated user info. At least one key to be updated (name or
admin) is required.
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: the new name (optional, if another key is updated
i.e. admin)
admin:
type: boolean
description: update admin (optional, if another key is updated
i.e. name)
required: true
responses:
200:
description: The updated user info
content:
application/json:
schema:
$ref: "#/components/schemas/User"
security:
- oauth2:
- admin:users
/users/{name}/activity:
post:
operationId: post-user-activity
summary: Notify Hub of activity for a given user
description: Notify the Hub of activity by the user, e.g. accessing a
service or (more likely) actively using a server.
parameters:
- $ref: "#/components/parameters/userName"
requestBody:
content:
application/json:
schema:
type: object
properties:
last_activity:
type: string
description: |
Timestamp of last-seen activity for this user.
Only needed if this is not activity associated
with using a given server.
format: date-time
servers:
type: object
properties:
:
required:
- last_activity
type: object
properties:
last_activity:
type: string
description: |
Timestamp of last-seen activity on this server.
format: date-time
description: |
Activity for a single server.
description: |
Register activity for specific servers by name.
The keys of this dict are the names of servers.
The default server has an empty name ('').
example:
last_activity: 2019-02-06T12:54:14Z
servers:
"":
last_activity: 2019-02-06T12:54:14Z
gpu:
last_activity: 2019-02-06T12:54:14Z
required: false
responses:
200:
description: Successfully updated activity
401:
description: Authentication/Authorization error
content: {}
404:
description: No such user
content: {}
security:
- oauth2:
- users:activity
/users/{name}/server:
post:
operationId: post-user-server
summary: Start a user's single-user notebook server
parameters:
- $ref: "#/components/parameters/userName"
requestBody:
description: |
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.
content:
application/json:
schema:
type: object
required: false
responses:
201:
description: The user's notebook server has started
content: {}
202:
description: The user's notebook server has not yet started, but has
been requested
content: {}
security:
- oauth2:
- servers
delete:
operationId: delete-user-server
summary: Stop a user's server
parameters:
- $ref: "#/components/parameters/userName"
responses:
202:
description: The user's notebook server has not yet stopped as it is
taking a while to stop
content: {}
204:
description: The user's notebook server has stopped
content: {}
security:
- oauth2:
- delete:servers
/users/{name}/servers/{server_name}:
post:
operationId: post-user-server-name
summary: Start a user's named server
parameters:
- $ref: "#/components/parameters/userName"
- $ref: "#/components/parameters/serverName"
requestBody:
description: |
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.
content:
application/json:
schema:
type: object
required: false
responses:
201:
description: The user's notebook named-server has started
content: {}
202:
description: The user's notebook named-server has not yet started, but
has been requested
content: {}
security:
- oauth2:
- servers
delete:
operationId: delete-user-server-name
summary: Stop a user's named server
description: |
To remove the named server in addition to deleting it,
the body may be a JSON dictionary with a boolean `remove` field:
```json
{"remove": true}
```
parameters:
- $ref: "#/components/parameters/userName"
- $ref: "#/components/parameters/serverName"
# FIXME: we probably shouldn't have request bodies on DELETE
requestBody:
content:
application/json:
schema:
type: object
properties:
remove:
type: boolean
description: |
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.
required: false
responses:
202:
description: The user's notebook named-server has not yet stopped as
it is taking a while to stop
content: {}
204:
description: The user's notebook named-server has stopped
content: {}
security:
- oauth2:
- delete:servers
/users/{name}/shared:
get:
operationId: get-user-shared
summary: List servers shared with user
description: Returns list of Shares granting the user access to servers
owned by others (new in 5.0)
parameters:
- $ref: "#/components/parameters/userName"
responses:
200:
description: Shared access granted to the user
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedList"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/ShareCode"
security:
- oauth2:
- read:users:shares
/users/{name}/shared/{owner}/{server_name}:
get:
operationId: get-user-shared-server
summary: |
Get user's shared access to server
description: |
Gets the Share representing a single user's access to a single server.
Users generally have access to this endpoint for themselves.
(new in 5.0)
parameters:
- $ref: "#/components/parameters/userName"
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
responses:
200:
description: The permissions granted to `user` on `owner/server`.
content:
application/json:
schema:
$ref: "#/components/schemas/Share"
security:
- oauth2:
- read:users:shares
delete:
operationId: delete-user-shared-server
summary: |
Leave a shared server
description: |
Revokes a user's access to a shared server by deleting.
Users generally have access to this endpoint for themselves.
(new in 5.0)
parameters:
- $ref: "#/components/parameters/userName"
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
responses:
204:
description: |
Permission has been revoked,
the user no longer has access to the server.
content: {}
security:
- oauth2:
- users:shares
/users/{name}/tokens:
get:
operationId: get-user-tokens
summary: List tokens for the user
parameters:
- $ref: "#/components/parameters/userName"
responses:
200:
description: The list of tokens
content:
application/json:
schema:
type: object
properties:
api_tokens:
type: array
items:
$ref: "#/components/schemas/Token"
401:
description: Authentication/Authorization error
content: {}
404:
description: No such user
content: {}
security:
- oauth2:
- read:tokens
post:
operationId: post-user-tokens
summary: Create a new token for the user
description: |
Creates a new token owned by the user.
Permissions can be limited by specifying a list of `scopes` in the JSON request body
(starting in JupyterHub 3.0; previously, permissions could be specified as `roles`,
which is deprecated in 3.0).
parameters:
- $ref: "#/components/parameters/userName"
requestBody:
content:
application/json:
schema:
type: object
properties:
expires_in:
type: number
example: 3600
description: lifetime (in seconds) after which the requested
token will expire. Omit, or specify null or 0 for no
expiration.
note:
type: string
description: A note attached to the token for future
bookkeeping
roles:
type: array
description: |
A list of role names from which to derive scopes.
This is a shortcut for assigning collections of scopes;
Tokens do not retain role assignment.
(Changed in 3.0: roles are immediately resolved to scopes
instead of stored on roles.)
items:
type: string
scopes:
type: array
description: |
A list of scopes that the token should have.
(new in JupyterHub 3.0).
items:
type: string
required: false
responses:
201:
description: The newly created token
content:
application/json:
schema:
$ref: "#/components/schemas/NewToken"
400:
description: Body must be a JSON dict or empty
content: {}
403:
description: Requested role does not exist
content: {}
security:
- oauth2:
- tokens
/users/{name}/tokens/{token_id}:
get:
operationId: get-user-token
summary: Get one token
description: Get the details for one token by id
parameters:
- $ref: "#/components/parameters/userName"
- name: token_id
in: path
required: true
schema:
type: string
responses:
200:
description: The info for the token
content:
application/json:
schema:
$ref: "#/components/schemas/Token"
security:
- oauth2:
- read:tokens
delete:
operationId: delete-user-token
summary: Delete (revoke) a token by id
parameters:
- $ref: "#/components/parameters/userName"
- name: token_id
in: path
required: true
schema:
type: string
responses:
204:
description: The token has been deleted
content: {}
security:
- oauth2:
- tokens
/groups:
get:
operationId: get-groups
summary: List groups
parameters:
- $ref: "#/components/parameters/paginationOffset"
- $ref: "#/components/parameters/paginationLimit"
responses:
200:
description: The list of groups
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Group"
security:
- oauth2:
- list:groups
/groups/{name}:
get:
operationId: get-group
summary: Get a group by name
parameters:
- $ref: "#/components/parameters/groupName"
responses:
200:
description: The group model
content:
application/json:
schema:
$ref: "#/components/schemas/Group"
security:
- oauth2:
- read:groups
post:
operationId: post-group
summary: Create a group
parameters:
- $ref: "#/components/parameters/groupName"
responses:
201:
description: The group has been created
content:
application/json:
schema:
$ref: "#/components/schemas/Group"
security:
- oauth2:
- admin:groups
delete:
operationId: delete-group
summary: Delete a group
parameters:
- $ref: "#/components/parameters/groupName"
responses:
204:
description: The group has been deleted
content: {}
security:
- oauth2:
- delete:groups
/groups/{name}/shared:
get:
operationId: get-group-shared
summary: List servers shared with group
description: |
Lists shares granting `group` access to shared servers
(new in 5.0)
parameters:
- $ref: "#/components/parameters/groupName"
responses:
200:
description: Shared access granted to the group
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedList"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Share"
security:
- oauth2:
- read:groups:shares
/groups/{name}/shared/{owner}/{server_name}:
get:
operationId: get-group-shared-server
summary: Get group's shared access
description: |
Get the Share representing a single group's access to a single server
(new in 5.0)
parameters:
- $ref: "#/components/parameters/groupName"
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
responses:
200:
description: The permissions granted to members of `group` on
`owner/server`
content:
application/json:
schema:
$ref: "#/components/schemas/Share"
security:
- oauth2:
- read:groups:shares
delete:
operationId: delete-group-shared-server
summary: Leave a share (group)
description: |
Leave a share by revoking a group's permissions on a single server
(new in 5.0)
parameters:
- $ref: "#/components/parameters/groupName"
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
responses:
204:
description: |
Permission has been revoked,
the group members no longer have access to the server.
content: {}
security:
- oauth2:
- groups:shares
/groups/{name}/users:
post:
operationId: post-group-users
summary: Add users to a group
parameters:
- $ref: "#/components/parameters/groupName"
requestBody:
description: The users to add to the group
content:
application/json:
schema:
type: object
properties:
users:
type: array
description: List of usernames to add to the group
items:
type: string
required: true
responses:
200:
description: The users have been added to the group
content:
application/json:
schema:
$ref: "#/components/schemas/Group"
security:
- oauth2:
- groups
delete:
operationId: delete-group-users
summary: |
Remove users from a group
description: |
Body should be a JSON dictionary
where `users` is a list of usernames to remove from the groups.
```json
{
"users": ["name1", "name2"]
}
```
parameters:
- $ref: "#/components/parameters/groupName"
requestBody:
description: The users to remove from the group
content:
application/json:
schema:
type: object
properties:
users:
type: array
description: List of usernames to remove from the group
items:
type: string
required: true
responses:
200:
description: The users have been removed from the group
content: {}
security:
- oauth2:
- groups
/groups/{name}/properties:
put:
operationId: put-group-properties
summary: Set group properties
description: |
Set properties on a group
(new in 3.2)
parameters:
- $ref: "#/components/parameters/groupName"
requestBody:
description: The new group properties, as a JSON dict.
content:
application/json:
schema:
type: object
required: true
responses:
200:
description: |
The properties have been updated.
The updated group model is returned.
content:
application/json:
schema:
$ref: "#/components/schemas/Group"
security:
- oauth2:
- groups
/shares/{owner}:
get:
operationId: get-shares-owner
summary: List shares by owner
description: |
List shares granting access to any of owner's servers
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/paginationOffset"
- $ref: "#/components/parameters/paginationLimit"
responses:
200:
description: The list of shares for any of the user's servers
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedList"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Share"
security:
- oauth2:
- read:shares
/shares/{owner}/{server_name}:
get:
operationId: get-shares-server
summary: List server shares
description: |
List shares granting access to a single server
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
- $ref: "#/components/parameters/paginationOffset"
- $ref: "#/components/parameters/paginationLimit"
responses:
200:
description: The list of shares granting access to the given server
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedList"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Share"
security:
- oauth2:
- read:shares
post:
operationId: post-shares-server
summary: Grant shared access
description: |
Grant shared access to a single server
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
requestBody:
description: The new group properties, as a JSON dict.
content:
application/json:
schema:
type: object
properties:
# expires_in not implemented, for now at least
# expires_in:
# type: number
# description: |
# expiration in seconds.
# If unspecified, no expiration.
group:
type: string
description: |
group to grant permissions to.
Exactly one of 'user' and 'group' can be specified.
user:
type: string
description: |
user to grant permissions to.
Exactly one of 'user' and 'group' can be specified.
scopes:
type: array
description: scopes to grant
items:
type: string
required: true
responses:
200:
description: The updated Share permissions
content:
application/json:
schema:
$ref: "#/components/schemas/Share"
security:
- oauth2:
- shares
- read:users:name
- read:groups:name
patch:
operationId: patch-shares-server
summary: Revoke shared access
description: |
Revoke shared access to a single server for a single user or group.
If scopes are specified, only the specified scopes are revoked,
allowing the target user or group to retain partial access.
Revocation is idempotent - revoking a scope not held does not result in an error.
The resulting Share model is returned if any scopes remain.
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
requestBody:
description: The share modifications to be made, as a JSON dict.
content:
application/json:
schema:
type: object
properties:
group:
type: string
description: |
group to revoke permissions from.
Exactly one of 'user' and 'group' must be specified.
user:
type: string
description: |
user to revoke permissions from.
Exactly one of 'user' and 'group' must be specified.
scopes:
type: array
description: |
scopes to revoke.
If no scopes are specified, all permissions are revoked.
items:
type: string
required: true
responses:
200:
description: |
The updated Share permissions.
An empty dict if no permissions remain.
content:
application/json:
schema:
$ref: "#/components/schemas/Share"
security:
- oauth2:
- shares
- read:users:name
- read:groups:name
delete:
operationId: delete-shares-server
summary: Revoke all shared access
description: |
Revoke all shared access to a given server
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
responses:
204:
description: |
All shares for the server have been deleted
security:
- oauth2:
- shares
/share-codes/{owner}:
get:
operationId: get-share-codes-owner
summary: List share codes by owner
description: |
List share codes granting access to a user's servers
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/paginationOffset"
- $ref: "#/components/parameters/paginationLimit"
responses:
200:
description: The list of share codes
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedList"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/ShareCode"
security:
- oauth2:
- read:shares
/share-codes/{owner}/{server_name}:
get:
operationId: get-share-codes-server
summary: List share codes
description: |
List share codes which can be exchanged for access to a single server
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
- $ref: "#/components/parameters/paginationOffset"
- $ref: "#/components/parameters/paginationLimit"
responses:
200:
description: The list of share codes
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/PaginatedList"
- type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/ShareCode"
security:
- oauth2:
- read:shares
post:
operationId: post-share-code
summary: Issue share code
description: |
Issue a share code, which can be exchanged for shared access to a single server
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
requestBody:
description: The new share code properties, as a JSON dict.
content:
application/json:
schema:
type: object
properties:
expires_in:
type: number
description: |
expiration in seconds.
If unspecified, expires in one day (86400)
scopes:
type: array
description: scopes to grant
items:
type: string
required: true
responses:
200:
description: |
The Share code you just created.
The code itself will be in the `code` field.
The code is not stored by JupyterHub and cannot be retrieved a second time.
`accept_url` will be the actual URL to share
(it will look like `/hub/accept-share?code=abc123`).
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ShareCode"
- type: object
properties:
code:
type: string
description: The share code itself
example: abc123
accept_url:
type: string
description: The URL path for accepting the code
example: /hub/accept-share?code=abc123
full_accept_url:
type:
- string
- "null"
description: |
The full URL for accepting the code,
if JupyterHub.public_url configuration is defined.
example:
https://hub.example.org/hub/accept-share?code=abc123
security:
- oauth2:
- shares
delete:
operationId: delete-share-code
summary: Revoke share code
description: |
Revoke a share code by id or code.
Exactly one of `id` or `code` must be specified.
(new in 5.0)
parameters:
- $ref: "#/components/parameters/sharedServerOwner"
- $ref: "#/components/parameters/sharedServerName"
- in: query
name: code
description: the share code to revoke
schema:
type: string
- in: query
name: id
description: the id of the share code to revoke
schema:
type: string
responses:
204:
description: |
The share code has been revoked.
content: {}
security:
- oauth2:
- shares
/services:
get:
operationId: get-services
summary: List services
parameters:
- $ref: "#/components/parameters/paginationOffset"
- $ref: "#/components/parameters/paginationLimit"
responses:
200:
description: The service list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Service"
security:
- oauth2:
- read:services
/services/{name}:
get:
operationId: get-service
summary: Get a service by name
parameters:
- name: name
in: path
description: service name
required: true
schema:
type: string
responses:
200:
description: The Service model
content:
application/json:
schema:
$ref: "#/components/schemas/Service"
security:
- oauth2:
- read:services
/proxy:
get:
operationId: get-proxy
summary: Get the proxy's routing table
description: A convenience alias for getting the routing table directly
from the proxy
parameters:
- $ref: "#/components/parameters/paginationOffset"
- $ref: "#/components/parameters/paginationLimit"
responses:
200:
description: Routing table
content:
application/json:
schema:
type: object
description: configurable-http-proxy routing table (see
configurable-http-proxy docs for details)
security:
- oauth2:
- proxy
post:
operationId: post-proxy
summary: Force the Hub to sync with the proxy
responses:
200:
description: Success
content: {}
security:
- oauth2:
- proxy
patch:
operationId: patch-proxy
summary: Notify the Hub about a new proxy
description: Notifies the Hub of a new proxy to use.
requestBody:
description: Any values that have changed for the new proxy. All keys
are optional.
content:
application/json:
schema:
type: object
properties:
ip:
type: string
description: IP address of the new proxy
port:
type: string
description: Port of the new proxy
protocol:
type: string
description: Protocol of new proxy, if changed
auth_token:
type: string
description: CONFIGPROXY_AUTH_TOKEN for the new proxy
required: true
responses:
200:
description: Success
content: {}
security:
- oauth2:
- proxy
/authorizations/token:
post:
deprecated: true
operationId: post-auth-token
summary: Request a new API token
description: |
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).
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
password:
type: string
required: false
responses:
200:
description: The new API token
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: The new API token.
403:
description: The user can not be authenticated.
content: {}
security:
- oauth2:
- tokens
/authorizations/token/{token}:
get:
deprecated: true
operationId: get-auth-token
summary: Identify a user or service from an API token
parameters:
- name: token
in: path
required: true
schema:
type: string
responses:
200:
description: The user or service identified by the API token
content: {}
404:
description: A user or service is not found.
content: {}
security:
- oauth2:
- (no_scope)
/authorizations/cookie/{cookie_name}/{cookie_value}:
get:
operationId: get-auth-cookie
summary: Identify a user from a cookie
description: Used by single-user notebook servers to hand off cookie
authentication to the Hub
parameters:
- name: cookie_name
in: path
required: true
schema:
type: string
- name: cookie_value
in: path
required: true
schema:
type: string
responses:
200:
description: The user identified by the cookie
content:
application/json:
schema:
$ref: "#/components/schemas/User"
404:
description: A user is not found.
content: {}
deprecated: true
/oauth2/authorize:
get:
operationId: get-oauth-authorize
summary: OAuth 2.0 authorize endpoint
description: |
Redirect users to this URL to begin the OAuth process.
It is not an API endpoint.
parameters:
- name: client_id
in: query
description: The client id
required: true
schema:
type: string
- name: response_type
in: query
description: The response type (always 'code')
required: true
schema:
type: string
- name: state
in: query
description: A state string
schema:
type: string
- name: redirect_uri
in: query
description: The redirect url
required: true
schema:
type: string
responses:
200:
description: Success
content: {}
400:
description: OAuth2Error
content: {}
/oauth2/token:
post:
operationId: post-oauth-token
summary: Request an OAuth2 token
description: |
Request an OAuth2 token from an authorization code.
This request completes the OAuth process.
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- client_id
- client_secret
- code
- grant_type
- redirect_uri
properties:
client_id:
type: string
description: The client id
client_secret:
type: string
description: The client secret
grant_type:
type: string
description: The grant type (always 'authorization_code')
enum:
- authorization_code
code:
type: string
description: The code provided by the authorization redirect
redirect_uri:
type: string
description: The redirect url
required: true
responses:
200:
description: JSON response including the token
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
description: The new API token for the user
token_type:
type: string
description: Will always be 'Bearer'
/shutdown:
post:
operationId: post-shutdown
summary: Shutdown the Hub
requestBody:
content:
application/json:
schema:
type: object
properties:
proxy:
type: boolean
description: Whether the proxy should be shutdown as well
(default from Hub config)
servers:
type: boolean
description: Whether users' notebook servers should be
shutdown as well (default from Hub config)
required: false
responses:
202:
description: Shutdown successful
content: {}
400:
description: Unexpected value for proxy or servers
content: {}
security:
- oauth2:
- shutdown
components:
parameters:
userName:
name: name
in: path
description: username
required: true
schema:
type: string
groupName:
name: name
in: path
description: group name
required: true
schema:
type: string
serverName:
name: server_name
in: path
description: |
name given to a named-server (empty string for default server).
Note that depending on your JupyterHub infrastructure there are limitations 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).
required: true
schema:
type: string
paginationOffset:
name: offset
in: query
description: |
Return a number of results, starting at the specified offset.
Can be used with limit to paginate.
If unspecified, return all items.
required: false
schema:
type: number
paginationLimit:
name: limit
in: query
description: |
Return a finite number of results.
Can be used with offset to paginate.
If unspecified, use api_page_default_limit.
required: false
schema:
type: number
sharedServerOwner:
name: owner
in: path
description: name of the user who owns the shared server
required: true
schema:
type: string
sharedServerName:
name: server_name
in: path
description: |
name of the shared server
(empty string for default server, which means the URL ends with a trailing '/', e.g. `/username/`).
required: true
schema:
type: string
schemas:
Pagination:
type: object
description: page info for paginated endpoints
properties:
total:
type: number
description: total number of results for the query
limit:
type: number
description: the maximum number of results
offset:
type: number
description: the starting point for this
next:
description: |
fields for the next page, if any.
Null if this is the last page.
type:
- object
- "null"
properties:
offset:
type: number
description: the offset for the next page
limit:
type: number
description: the same as the above limit, for consistency
url:
type: string
description: |
the assembled url for the next page,
with query parameters already included.
PaginatedList:
type: object
properties:
items:
type: array
items:
type: object
_pagination:
$ref: "#/components/schemas/Pagination"
User:
type: object
properties:
name:
type: string
description: The user's name
kind:
type: string
description: the string 'user' to distinguish from 'service'
enum:
- user
admin:
type: boolean
description: Whether the user is an admin
roles:
type: array
description: The names of roles this user has
items:
type: string
groups:
type: array
description: The names of groups where this user is a member
items:
type: string
server:
type: string
description: The user's notebook server's base URL, if running; null
if not.
pending:
type: string
description: The currently pending action, if any
enum:
- spawn
- stop
last_activity:
type: string
description: Timestamp of last-seen activity from the user
format: date-time
servers:
type: object
description: |
The servers for this user.
By default: only includes _active_ servers.
Changed in 3.0: if `?include_stopped_servers` parameter is specified,
stopped servers will be included as well.
additionalProperties:
$ref: "#/components/schemas/Server"
auth_state:
type: object
properties: {}
description: |
Authentication state of the user. Only available with admin:users:auth_state
scope. None otherwise.
Server:
type: object
properties:
name:
type: string
description: The server's name. The user's default server has an empty
name ('')
ready:
type: boolean
description: |
Whether the server is ready for traffic.
Will always be false when any transition is pending.
stopped:
type: boolean
description: |
Whether the server is stopped. Added in JupyterHub 3.0,
and only useful when using the `?include_stopped_servers`
request parameter.
Now that stopped servers may be included (since JupyterHub 3.0),
this is the simplest way to select stopped servers.
Always equivalent to `not (ready or pending)`.
pending:
type: string
description: |
The currently pending action, if any.
A server is not ready if an action is pending.
enum:
- spawn
- stop
url:
type: string
description: |
The URL path where the server can be accessed
(typically /user/:name/:server.name/).
Will be a full URL if subdomains are configured.
progress_url:
type: string
description: |
The URL path for an event-stream to retrieve events during a spawn.
full_url:
type:
- string
- "null"
description: |
The full URL of the server (`https://hub.example.org/user/:name/:servername`).
`null` unless JupyterHub.public_url or subdomains are configured.
Added in 5.0.
full_progress_url:
type:
- string
- "null"
description: |
The full URL for the progress events (`https://hub.example.org/hub/api/users/:name/servers/:servername/progress`).
`null` unless JupyterHub.public_url is configured.
Added in 5.0.
started:
type: string
description: UTC timestamp when the server was last started.
format: date-time
last_activity:
type: string
description: UTC timestamp last-seen activity on this server.
format: date-time
state:
type: object
properties: {}
description: Arbitrary internal state from this server's spawner. Only
available on the hub's users list or get-user-by-name method, and
only with admin:users:server_state scope. None otherwise.
user_options:
type: object
properties: {}
description: User specified options for the user's spawned instance of
a single-user server.
RequestIdentity:
description: |
The model for the entity making the request.
Extends User or Service model to add information about the specific credentials (e.g. session or token-authorised scopes).
allOf:
- type: object
oneOf:
- $ref: "#/components/schemas/User"
- $ref: "#/components/schemas/Service"
discriminator:
propertyName: kind
mapping:
user: "#/components/schemas/User"
service: "#/components/schemas/Service"
- type: object
properties:
kind:
type: string
description: |
'user' or 'service' depending on the entity which owns the token
enum:
- user
- service
session_id:
type:
- string
- "null"
description: |
The session id associated with the request's OAuth token, if any.
null, if the request token not associated with a session id.
Added in 2.0.
scopes:
type: array
description: |
The list of all expanded scopes the request credentials have access to.
Added in 2.0.
items:
type: string
example:
- "read:users"
- "access:servers!user=name"
token_id:
type:
- string
- "null"
description: |
The id of the token authorizing the request, if any.
This id can be used to revoke the token via the API.
Null if the request is not authorized with a token.
Added in 5.0.
Group:
type: object
properties:
name:
type: string
description: The group's name
kind:
type: string
description: Always the string 'group'
enum:
- group
users:
type: array
description: The names of users who are members of this group
items:
type: string
properties:
type: object
description: |
Group properties (a dictionary).
Unused by JupyterHub itself,
but an extension point to store information about groups.
Added in JupyterHub 3.2.
roles:
type: array
description: The names of roles this group has
items:
type: string
Service:
type: object
properties:
name:
type: string
description: The service's name
kind:
type: string
description: the string 'service' to distinguish from 'user'
enum:
- service
admin:
type: boolean
description: Whether the service is an admin
roles:
type: array
description: The names of roles this service has
items:
type: string
url:
type: string
description: The internal url where the service is running
prefix:
type: string
description: The proxied URL prefix to the service's url
pid:
type: number
description: The PID of the service process (if managed)
command:
type: array
description: The command used to start the service (if managed)
items:
type: string
info:
type: object
properties: {}
description: |
Additional information a deployment can attach to a service.
JupyterHub does not use this field.
SharedServer:
description: Subset of Server model present in Share responses
type: object
properties:
# these are the minimal subset of a server model needed for access
# e.g. where is it (name, url), whose is it (user.name), and is it running (ready)
name:
type: string
description: the server name. '' for the default server.
url:
type: string
description: the server's URL (path only when not using subdomains)
full_url:
type:
- string
- "null"
description: |
The full URL of the server (`https://hub.example.org/user/:name/:servername`).
`null` unless JupyterHub.public_url or subdomains are configured.
ready:
type: boolean
description: whether the server is ready
user:
type: object
description: the server's owner
properties:
name:
type: string
Share:
description: |
A single sharing permission.
There is at most one of these objects per (server, user) or (server, group) combination.
type: object
properties:
server:
description: the server granting shared access
$ref: "#/components/schemas/SharedServer"
scopes:
description: the scopes granted by this Share
type: array
items:
type: string
group:
description: the group being shared with (exactly one of 'user' or
'group' will be non-null, the other will be null)
type:
- object
- "null"
properties:
name:
type: string
user:
description: the user being shared with (exactly one of 'user' or
'group' will be non-null, the other will be null)
type:
- object
- "null"
properties:
name:
type: string
created_at:
description: when the share was first granted
type: string
format: date-time
ShareCode:
description: A single sharing code. There is at most one of these objects
per (server, user) or (server, group) combination.
type: object
properties:
server:
description: the server granting shared access
$ref: "#/components/schemas/SharedServer"
scopes:
description: the scopes granted by this Share
type: array
items:
type: string
id:
type: string
description: |
the share-code's id.
Can be used to revoke share codes.
created_at:
description: when the share code was issued
type: string
format: date-time
expires_at:
description: |
When the share code will expire,
always in the future.
`null` if the code does not expire.
type:
- string
- "null"
format: date-time
Token:
type: object
properties:
id:
type: string
description: The id of the API token. Used for modifying or deleting
the token.
user:
type: string
description: The user that owns a token (undefined if owned by a
service)
service:
type: string
description: The service that owns the token (undefined of owned by a
user)
roles:
type: array
description: Deprecated in JupyterHub 3, always an empty list. Tokens
have 'scopes' starting from JupyterHub 3.
items:
type: string
scopes:
type: array
description: List of scopes this token has been assigned. New in
JupyterHub 3. In JupyterHub 2.x, tokens were assigned 'roles'
instead of scopes.
items:
type: string
note:
type: string
description: A note about the token, typically describing what it was
created for.
created:
type: string
description: Timestamp when this token was created
format: date-time
expires_at:
type: string
description: Timestamp when this token expires. Null if there is no
expiry.
format: date-time
last_activity:
type: string
description: |
Timestamp of last-seen activity using this token.
Can be null if token has never been used.
format: date-time
session_id:
type:
- string
- "null"
description: |
The session id associated with the token, if any.
Only used for tokens set during oauth flows.
Added in 2.0.
NewToken:
type: object
properties:
token:
type: string
description: The token itself. Only present in responses to requests
for a new token.
id:
type: string
description: The id of the API token. Used for modifying or deleting
the token.
user:
type: string
description: The user that owns a token (undefined if owned by a
service)
service:
type: string
description: The service that owns the token (undefined of owned by a
user)
roles:
type: array
description: Deprecated in JupyterHub 3, always an empty list. Tokens
have 'scopes' starting from JupyterHub 3.
items:
type: string
scopes:
type: array
description: List of scopes this token has been assigned. New in
JupyterHub 3. In JupyterHub 2.x, tokens were assigned 'roles'
instead of scopes.
items:
type: string
note:
type: string
description: A note about the token, typically describing what it was
created for.
created:
type: string
description: Timestamp when this token was created
format: date-time
expires_at:
type: string
description: Timestamp when this token expires. Null if there is no
expiry.
format: date-time
last_activity:
type: string
description: |
Timestamp of last-seen activity using this token.
Can be null if token has never been used.
format: date-time
session_id:
type:
- string
- "null"
description: |
The session id associated with the token, if any.
Only used for tokens set during oauth flows.
Added in 2.0.
securitySchemes:
token:
type: http
scheme: bearer
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: /hub/api/oauth2/authorize
tokenUrl: /hub/api/oauth2/token
scopes:
(no_scope): Identify the owner of the requesting entity.
self: The user’s own resources _(metascope for users, resolves to
(no_scope) for services)_
inherit: Everything that the token-owning entity can access
_(metascope for tokens)_
admin-ui: Access the admin page. Permission to take actions via the
admin page granted separately.
admin:users: Read, modify, create, and delete users and their
authentication state, not including their servers or tokens. This
is an extremely privileged scope and should be considered
tantamount to superuser.
admin:auth_state: Read a user’s authentication state.
users: Read and write permissions to user models (excluding servers,
tokens and authentication state).
delete:users: Delete users.
list:users: List users, including at least their names.
read:users: Read user models (including the URL of the default
server if it is running).
read:users:name: Read names of users.
read:users:groups: Read users’ group membership.
read:users:activity: Read time of last user activity.
read:roles: Read role assignments.
read:roles:users: Read user role assignments.
read:roles:services: Read service role assignments.
read:roles:groups: Read group role assignments.
users:activity: Update time of last user activity.
admin:servers: Read, start, stop, create and delete user servers and
their state.
admin:server_state: Read and write users’ server state.
servers: Start and stop user servers.
read:servers: Read users’ names and their server models (excluding
the server state).
delete:servers: Stop and delete users' servers.
tokens: Read, write, create and delete user tokens.
read:tokens: Read user tokens.
admin:groups: Read and write group information, create and delete
groups.
groups: 'Read and write group information, including adding/removing any
users to/from groups. Note: adding users to groups may affect permissions.'
list:groups: List groups, including at least their names.
read:groups: Read group models.
read:groups:name: Read group names.
delete:groups: Delete groups.
admin:services: Create, read, update, delete services, not including
services defined from config files.
list:services: List services, including at least their names.
read:services: Read service models.
read:services:name: Read service names.
read:hub: Read detailed information about the Hub.
access:servers: Access user servers via API or browser.
access:services: Access services via API or browser.
users:shares: Read and revoke a user's access to shared servers.
read:users:shares: Read servers shared with a user.
groups:shares: Read and revoke a group's access to shared servers.
read:groups:shares: Read servers shared with a group.
read:shares: Read information about shared access to servers.
shares: Manage access to shared servers.
proxy: Read information about the proxy’s routing table, sync the
Hub with the proxy and notify the Hub about a new proxy.
shutdown: Shutdown the hub.
read:metrics: Read prometheus metrics.