# see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default
swagger: '2.0'
info:
  title: JupyterHub
  description: The REST API for JupyterHub
  version: 0.9.0dev
  license:
    name: BSD-3-Clause
schemes:
  - [http, https]
securityDefinitions:
  token:
    type: apiKey
    name: Authorization
    in: header
security:
  - token: []
basePath: /hub/api
produces:
  - application/json
consumes:
  - application/json
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
          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
          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
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: The Hub's user list
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
    post:
      summary: Create multiple users
      parameters:
        - name: data
          in: body
          required: true
          schema:
            type: object
            properties:
              usernames:
                type: array
                description: list of usernames to create on the Hub
                items:
                  type: string
              admin:
                description: whether the created users should be admins
                type: boolean
      responses:
        '201':
          description: The users have been created
          schema:
            type: array
            description: The created users
            items:
              $ref: '#/definitions/User'
  /users/{name}:
    get:
      summary: Get a user by name
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
      responses:
        '200':
          description: The User model
          schema:
            $ref: '#/definitions/User'
    post:
      summary: Create a single user
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
      responses:
        '201':
          description: The user has been created
          schema:
            $ref: '#/definitions/User'
    patch:
      summary: Modify a user
      description: Change a user's name or admin status
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
        - name: data
          in: body
          required: true
          description: Updated user info. At least one key to be updated (name or admin) is required.
          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)
      responses:
        '200':
          description: The updated user info
          schema:
            $ref: '#/definitions/User'
    delete:
      summary: Delete a user
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The user has been deleted
  /users/{name}/server:
    post:
      summary: Start a user's single-user notebook server
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
      responses:
        '201':
          description: The user's notebook server has started
        '202':
          description: The user's notebook server has not yet started, but has been requested
    delete:
      summary: Stop a user's server
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The user's notebook server has stopped
        '202':
          description: The user's notebook server has not yet stopped as it is taking a while to stop
  /users/{name}/servers/{server_name}:
    post:
      summary: Start a user's single-user named-server notebook server
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
        - name: server_name
          description: name given to a named-server
          in: path
          required: true
          type: string
        - name: remove
          description: |
            Whether to fully remove the server, rather than just stop it.
            Removing a server deletes things like the state of the stopped server.
          in: body
          required: false
          type: boolean
      responses:
        '201':
          description: The user's notebook named-server has started
        '202':
          description: The user's notebook named-server has not yet started, but has been requested
    delete:
      summary: Stop a user's named-server
      parameters:
        - name: name
          description: username
          in: path
          required: true
          type: string
        - name: server_name
          description: name given to a named-server
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The user's notebook named-server has stopped
        '202':
          description: The user's notebook named-server has not yet stopped as it is taking a while to stop
  /users/{name}/tokens:
    get:
      summary: List tokens for the user
      responses:
        '200':
          description: The list of tokens
          schema:
            type: array
            items:
              $ref: '#/definitions/Token'
    post:
      summary: Create a new token for the user
      parameters:
        - name: expires_in
          type: number
          required: false
          in: body
          description: lifetime (in seconds) after which the requested token will expire.
        - name: note
          type: string
          required: false
          in: body
          description: A note attached to the token for future bookkeeping
      responses:
        '201':
          description: The newly created token
          schema:
            $ref: '#/definitions/Token'
  /users/{name}/tokens/{token_id}:
    get:
      summary: Get the model for a token by id
      responses:
        '200':
          description: The info for the new token
          schema:
            $ref: '#/definitions/Token'
    delete:
      summary: Delete (revoke) a token by id
      responses:
        '204':
          description: The token has been deleted
  /user:
    summary: Return authenticated user's model
    description:
    parameters:
    responses:
      '200':
        description: The authenticated user's model is returned.
  /groups:
    get:
      summary: List groups
      responses:
        '200':
          description: The list of groups
          schema:
            type: array
            items:
              $ref: '#/definitions/Group'
  /groups/{name}:
    get:
      summary: Get a group by name
      parameters:
        - name: name
          description: group name
          in: path
          required: true
          type: string
      responses:
        '200':
          description: The group model
          schema:
            $ref: '#/definitions/Group'
    post:
      summary: Create a group
      parameters:
        - name: name
          description: group name
          in: path
          required: true
          type: string
      responses:
        '201':
          description: The group has been created
          schema:
            $ref: '#/definitions/Group'
    delete:
      summary: Delete a group
      parameters:
        - name: name
          description: group name
          in: path
          required: true
          type: string
      responses:
        '204':
          description: The group has been deleted
  /groups/{name}/users:
    post:
      summary: Add users to a group
      parameters:
        - name: name
          description: group name
          in: path
          required: true
          type: string
        - name: data
          in: body
          required: true
          description: The users to add to the group
          schema:
            type: object
            properties:
              users:
                type: array
                description: List of usernames to add to the group
                items:
                  type: string
      responses:
        '200':
          description: The users have been added to the group
          schema:
            $ref: '#/definitions/Group'
    delete:
      summary: Remove users from a group
      parameters:
        - name: name
          description: group name
          in: path
          required: true
          type: string
        - name: data
          in: body
          required: true
          description: The users to remove from the group
          schema:
            type: object
            properties:
              users:
                type: array
                description: List of usernames to remove from the group
                items:
                  type: string
      responses:
        '200':
          description: The users have been removed from the group
  /services:
    get:
      summary: List services
      responses:
        '200':
          description: The service list
          schema:
            type: array
            items:
              $ref: '#/definitions/Service'
  /services/{name}:
    get:
      summary: Get a service by name
      parameters:
        - name: name
          description: service name
          in: path
          required: true
          type: string
      responses:
        '200':
          description: The Service model
          schema:
            $ref: '#/definitions/Service'
  /proxy:
    get:
      summary: Get the proxy's routing table
      description: A convenience alias for getting the routing table directly from the proxy
      responses:
        '200':
          description: Routing table
          schema:
            type: object
            description: configurable-http-proxy routing table (see configurable-http-proxy docs for details)
    post:
      summary: Force the Hub to sync with the proxy
      responses:
        '200':
          description: Success
    patch:
      summary: Notify the Hub about a new proxy
      description: Notifies the Hub of a new proxy to use.
      parameters:
        - name: data
          in: body
          required: true
          description: Any values that have changed for the new proxy. All keys are optional.
          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
      responses:
        '200':
          description: Success
  /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).
      parameters:
        - name: username
          in: body
          required: false
          type: string
        - name: password
          in: body
          required: false
          type: string
      responses:
        '200':
          description: The new API token
          schema:
            type: object
            properties:
              token:
                type: string
                description: The new API token.
        '403':
          description: The user can not be authenticated.
  /authorizations/token/{token}:
    get:
      summary: Identify a user or service from an API token
      parameters:
      - name: token
        in: path
        required: true
        type: string
      responses:
        '200':
          description: The user or service identified by the API token
        '404':
          description: A user or service is not found.
  /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
        type: string
      - name: cookie_value
        in: path
        required: true
        type: string
      responses:
        '200':
          description: The user identified by the cookie
          schema:
            $ref: '#/definitions/User'
        '404':
          description: A user is not found.
  /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
          description: The client id
          in: query
          required: true
          type: string
        - name: response_type
          description: The response type (always 'code')
          in: query
          required: true
          type: string
        - name: state
          description: A state string
          in: query
          required: false
          type: string
        - name: redirect_uri
          description: The redirect url
          in: query
          required: true
          type: string
  /oauth2/token:
    post:
      summary: Request an OAuth2 token
      description: |
        Request an OAuth2 token from an authorization code.
        This request completes the OAuth process.
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: client_id
          description: The client id
          in: form
          required: true
          type: string
        - name: client_secret
          description: The client secret
          in: form
          required: true
          type: string
        - name: grant_type
          description: The grant type (always 'authorization_code')
          in: form
          required: true
          type: string
        - name: code
          description: The code provided by the authorization redirect
          in: form
          required: true
          type: string
        - name: redirect_uri
          description: The redirect url
          in: form
          required: true
          type: string
      responses:
        '200':
          description: JSON response including the token
          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
      parameters:
        - name: proxy
          in: body
          type: boolean
          description: Whether the proxy should be shutdown as well (default from Hub config)
        - name: servers
          in: body
          type: boolean
          description: Whether users' notebook servers should be shutdown as well (default from Hub config)
definitions:
  User:
    type: object
    properties:
      name:
        type: string
        description: The user's name
      admin:
        type: boolean
        description: Whether the user is an admin
      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
        enum: ["spawn", "stop", null]
        description: The currently pending action, if any
      last_activity:
        type: string
        format: date-time
        description: Timestamp of last-seen activity from the user
      servers:
        type: object
        description: The active servers for this user.
        items:
          schema:
            $ref: '#/definitions/Server'
  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.
      pending:
        type: string
        enum: ["spawn", "stop", null]
        description: |
          The currently pending action, if any.
          A server is not ready if an action is pending.
      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
        format: date-time
        description: UTC timestamp when the server was last started.
      last_activity:
        type: string
        format: date-time
        description: UTC timestamp last-seen activity on this server.
      state:
        type: object
        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 if a hub admin.  None otherwise.
  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
  Service:
    type: object
    properties:
      name:
        type: string
        description: The service's name
      admin:
        type: boolean
        description: Whether the service is an admin
      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
        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)
      note:
        type: string
        description: A note about the token, typically describing what it was created for.
      created:
        type: string
        format: date-time
        description: Timestamp when this token was created
      expires_at:
        type: string
        format: date-time
        description: Timestamp when this token expires. Null if there is no expiry.
      last_activity:
        type: string
        format: date-time
        description: |
          Timestamp of last-seen activity using this token.
          Can be null if token has never been used.