mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 18:14:10 +00:00
1526 lines
46 KiB
YAML
1526 lines
46 KiB
YAML
openapi: 3.0.3
|
||
# note: 3.1.0 required for requestBody on DELETE
|
||
# which we should maybe move away from
|
||
info:
|
||
title: JupyterHub
|
||
description: The REST API for JupyterHub
|
||
license:
|
||
name: BSD-3-Clause
|
||
version: 5.0.0.dev
|
||
servers:
|
||
- url: /hub/api
|
||
security:
|
||
- token: []
|
||
- oauth2:
|
||
- self
|
||
paths:
|
||
/:
|
||
get:
|
||
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:
|
||
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:
|
||
summary: Return authenticated user's model
|
||
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:
|
||
- read:users
|
||
- read:users:name
|
||
- read:users:groups
|
||
- read:users:activity
|
||
- read:servers
|
||
- read:roles:users
|
||
- admin:auth_state
|
||
- admin:server_state
|
||
/users:
|
||
get:
|
||
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
|
||
- name: offset
|
||
in: query
|
||
description: |
|
||
Return a number users starting at the given offset.
|
||
Can be used with limit to paginate.
|
||
If unspecified, return all users.
|
||
schema:
|
||
type: number
|
||
- name: limit
|
||
in: query
|
||
description: |
|
||
Return a finite number of users.
|
||
Can be used with offset to paginate.
|
||
If unspecified, use api_page_default_limit.
|
||
schema:
|
||
type: number
|
||
- 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
|
||
responses:
|
||
200:
|
||
description: The Hub's user list
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/User"
|
||
security:
|
||
- oauth2:
|
||
- read:users
|
||
- read:users:name
|
||
- read:users:groups
|
||
- read:users:activity
|
||
- read:servers
|
||
- read:roles:users
|
||
- admin:auth_state
|
||
- admin:server_state
|
||
post:
|
||
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
|
||
x-codegen-request-body-name: body
|
||
/users/{name}:
|
||
get:
|
||
summary: Get a user by name
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- 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
|
||
- read:users:name
|
||
- read:users:groups
|
||
- read:users:activity
|
||
- read:servers
|
||
- read:roles:users
|
||
- admin:auth_state
|
||
- admin:server_state
|
||
post:
|
||
summary: Create a single user
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
201:
|
||
description: The user has been created
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/User"
|
||
security:
|
||
- oauth2:
|
||
- admin:users
|
||
delete:
|
||
summary: Delete a user
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
204:
|
||
description: The user has been deleted
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- admin:users
|
||
patch:
|
||
summary: Modify a user
|
||
description: Change a user's name or admin status
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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
|
||
x-codegen-request-body-name: body
|
||
/users/{name}/activity:
|
||
post:
|
||
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:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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:
|
||
<server name>:
|
||
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:
|
||
401:
|
||
description: Authentication/Authorization error
|
||
content: {}
|
||
404:
|
||
description: No such user
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- users:activity
|
||
x-codegen-request-body-name: body
|
||
/users/{name}/server:
|
||
post:
|
||
summary: Start a user's single-user notebook server
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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
|
||
x-codegen-request-body-name: options
|
||
delete:
|
||
summary: Stop a user's server
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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:
|
||
- servers
|
||
/users/{name}/servers/{server_name}:
|
||
post:
|
||
summary: Start a user's single-user named-server notebook server
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: server_name
|
||
in: path
|
||
description: |
|
||
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).
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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
|
||
x-codegen-request-body-name: options
|
||
delete:
|
||
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:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: server_name
|
||
in: path
|
||
description: name given to a named-server
|
||
required: true
|
||
schema:
|
||
type: string
|
||
|
||
# FIXME: openapi 3.1 is required for requestBody on DELETE
|
||
# 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:
|
||
- servers
|
||
# x-codegen-request-body-name: body
|
||
/users/{name}/tokens:
|
||
get:
|
||
summary: List tokens for the user
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
200:
|
||
description: The list of tokens
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Token"
|
||
401:
|
||
description: Authentication/Authorization error
|
||
content: {}
|
||
404:
|
||
description: No such user
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- read:tokens
|
||
post:
|
||
summary: |
|
||
Create a new token for the user.
|
||
Permissions can be limited by specifying a list of `scopes` in the JSON request body
|
||
(starting in JupyerHub 3.0; previously, permissions could be specified as `roles` could be specified,
|
||
which is deprecated in 3.0).
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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/Token"
|
||
400:
|
||
description: Body must be a JSON dict or empty
|
||
content: {}
|
||
403:
|
||
description: Requested role does not exist
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- tokens
|
||
x-codegen-request-body-name: token_params
|
||
/users/{name}/tokens/{token_id}:
|
||
get:
|
||
summary: Get the model for a token by id
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: token_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
200:
|
||
description: The info for the new token
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Token"
|
||
security:
|
||
- oauth2:
|
||
- read:tokens
|
||
delete:
|
||
summary: Delete (revoke) a token by id
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: token_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
204:
|
||
description: The token has been deleted
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- tokens
|
||
/groups:
|
||
get:
|
||
summary: List groups
|
||
parameters:
|
||
- name: offset
|
||
in: query
|
||
description: |
|
||
Return a number of groups starting at the specified offset.
|
||
Can be used with limit to paginate.
|
||
If unspecified, return all groups.
|
||
schema:
|
||
type: number
|
||
- name: limit
|
||
in: query
|
||
description: |
|
||
Return a finite number of groups.
|
||
Can be used with offset to paginate.
|
||
If unspecified, use api_page_default_limit.
|
||
schema:
|
||
type: number
|
||
responses:
|
||
200:
|
||
description: The list of groups
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Group"
|
||
security:
|
||
- oauth2:
|
||
- read:groups
|
||
- read:groups:name
|
||
- read:roles:groups
|
||
/groups/{name}:
|
||
get:
|
||
summary: Get a group by name
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: group name
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
200:
|
||
description: The group model
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Group"
|
||
security:
|
||
- oauth2:
|
||
- read:groups
|
||
- read:groups:name
|
||
- read:roles:groups
|
||
post:
|
||
summary: Create a group
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: group name
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
201:
|
||
description: The group has been created
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Group"
|
||
security:
|
||
- oauth2:
|
||
- admin:groups
|
||
delete:
|
||
summary: Delete a group
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: group name
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
204:
|
||
description: The group has been deleted
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- admin:groups
|
||
/groups/{name}/users:
|
||
post:
|
||
summary: Add users to a group
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: group name
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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
|
||
x-codegen-request-body-name: body
|
||
delete:
|
||
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:
|
||
- name: name
|
||
in: path
|
||
description: group name
|
||
required: true
|
||
schema:
|
||
type: string
|
||
# 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
|
||
x-codegen-request-body-name: body
|
||
/groups/{name}/properties:
|
||
put:
|
||
summary: |
|
||
Set the group properties.
|
||
|
||
Added in JupyterHub 3.2.
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: group name
|
||
required: true
|
||
schema:
|
||
type: string
|
||
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
|
||
x-codegen-request-body-name: body
|
||
/services:
|
||
get:
|
||
summary: List services
|
||
responses:
|
||
200:
|
||
description: The service list
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Service"
|
||
security:
|
||
- oauth2:
|
||
- read:services
|
||
- read:services:name
|
||
- read:roles:services
|
||
/services/{name}:
|
||
get:
|
||
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
|
||
- read:services:name
|
||
- read:roles:services
|
||
/proxy:
|
||
get:
|
||
summary: Get the proxy's routing table
|
||
description:
|
||
A convenience alias for getting the routing table directly from
|
||
the proxy
|
||
parameters:
|
||
- name: offset
|
||
in: query
|
||
description: |
|
||
Return a number of routes starting at the given offset.
|
||
Can be used with limit to paginate.
|
||
If unspecified, return all routes.
|
||
schema:
|
||
type: number
|
||
- name: limit
|
||
in: query
|
||
description: |
|
||
Return a finite number of routes.
|
||
Can be used with offset to paginate.
|
||
If unspecified, use api_page_default_limit
|
||
schema:
|
||
type: number
|
||
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:
|
||
summary: Force the Hub to sync with the proxy
|
||
responses:
|
||
200:
|
||
description: Success
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- proxy
|
||
patch:
|
||
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
|
||
x-codegen-request-body-name: body
|
||
/authorizations/token:
|
||
post:
|
||
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
|
||
x-codegen-request-body-name: credentials
|
||
/authorizations/token/{token}:
|
||
get:
|
||
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:
|
||
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:
|
||
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:
|
||
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:
|
||
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')
|
||
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:
|
||
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: Unexpeced value for proxy or servers
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- shutdown
|
||
x-codegen-request-body-name: body
|
||
components:
|
||
schemas:
|
||
User:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The user's name
|
||
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 where the server can be accessed
|
||
(typically /user/:name/:server.name/).
|
||
progress_url:
|
||
type: string
|
||
description: |
|
||
The URL for an event-stream to retrieve events during a spawn.
|
||
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:
|
||
session_id:
|
||
type: string
|
||
nullable: true
|
||
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"
|
||
Group:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The group's name
|
||
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
|
||
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.
|
||
Token:
|
||
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' insead 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
|
||
nullable: true
|
||
description: |
|
||
The session id associated with the token, if any.
|
||
Only used for tokens set during oauth flows.
|
||
|
||
Added in 2.0.
|
||
responses:
|
||
NotFound:
|
||
description: The specified resource was not found
|
||
content: {}
|
||
Unauthorized:
|
||
description: Authentication/Authorization error
|
||
content: {}
|
||
securitySchemes:
|
||
token:
|
||
type: apiKey
|
||
name: Authorization
|
||
in: header
|
||
oauth2:
|
||
type: oauth2
|
||
flows:
|
||
authorizationCode:
|
||
authorizationUrl: https://hub.example/hub/api/oauth2/authorize
|
||
tokenUrl: https://hub.example/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, write, create and delete users and their authentication
|
||
state, not including their servers or tokens.
|
||
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 (excluding including servers, tokens and
|
||
authentication state).
|
||
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 users
|
||
to/from groups.
|
||
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.
|
||
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.
|