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: 4.0.0 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 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: : 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 parameters: - name: name in: path description: username required: true schema: type: string requestBody: content: application/json: schema: type: object properties: expires_in: type: number description: lifetime (in seconds) after which the requested token will expire. 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: array 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. items: $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. 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.