openapi: 3.0.3
info:
  title: Girder REST API (Emory Digital Slide Archive) annotation user API
  version: 3.2.14
  description: OpenAPI 3.0 conversion of the Girder REST API powering the Emory Digital Slide Archive (computablebrain). Converted faithfully from the live Swagger 2.0 document at https://computablebrain.emory.edu/api/v1/describe.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
servers:
- url: https://computablebrain.emory.edu/api/v1
tags:
- description: user resource
  name: user
paths:
  /user:
    get:
      operationId: user_find_user
      parameters:
      - name: text
        in: query
        required: false
        description: Pass this to perform a full text search for items.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Result set size limit.
        schema:
          type: integer
          format: int32
          default: 50
      - name: offset
        in: query
        required: false
        description: Offset into result set.
        schema:
          type: integer
          format: int32
          default: 0
      - name: sort
        in: query
        required: false
        description: Field to sort the result set by.
        schema:
          type: string
          default: lastName
      - name: sortdir
        in: query
        required: false
        description: 'Sort order: 1 for ascending, -1 for descending.'
        schema:
          type: integer
          format: int32
          enum:
          - 1
          - -1
          default: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/User'
                type: array
        '400':
          description: A parameter was invalid.
      summary: List or search for users.
      tags:
      - user
    post:
      operationId: user_createUser_post_user
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: A parameter was invalid, or the specified login or email already exists in the system.
      summary: Create a new user.
      tags:
      - user
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                login:
                  type: string
                  description: The user's requested login.
                email:
                  type: string
                  description: The user's email address.
                firstName:
                  type: string
                  description: The user's first name.
                lastName:
                  type: string
                  description: The user's last name.
                password:
                  type: string
                  format: password
                  description: The user's requested password
                admin:
                  type: boolean
                  default: false
                  description: Whether this user should be a site administrator.
              required:
              - login
              - email
              - firstName
              - lastName
              - password
  /user/authentication:
    delete:
      description: Attempts to delete your authentication cookie.
      operationId: user_logout_delete_authentication
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: A parameter was invalid.
      summary: Log out of the system.
      tags:
      - user
      parameters: []
    get:
      description: Pass your username and password using HTTP Basic Auth. Sends a cookie that should be passed back in future requests.
      operationId: user_login_authentication
      parameters:
      - name: Girder-OTP
        in: header
        required: false
        description: A one-time password for this user
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: Missing Authorization header.
        '403':
          description: Invalid login or password.
      summary: Log in to the system.
      tags:
      - user
  /user/details:
    get:
      operationId: user_getUsersDetails_details
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
      summary: Get detailed information of accessible users.
      tags:
      - user
      parameters: []
  /user/me:
    get:
      operationId: user_getMe_me
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: A parameter was invalid.
      summary: Retrieve the currently logged-in user information.
      tags:
      - user
      parameters: []
  /user/password:
    put:
      operationId: user_changePassword_put_password
      parameters: []
      responses:
        '200':
          description: Success
        '400':
          description: Your new password is invalid.
        '401':
          description: 'You are not logged in.


            Your old password is incorrect.'
      summary: Change your password.
      tags:
      - user
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                old:
                  type: string
                  format: password
                  description: Your current password or a temporary access token.
                new:
                  type: string
                  format: password
                  description: Your new password.
              required:
              - old
              - new
  /user/password/temporary:
    put:
      operationId: user_generateTemporaryPassword_put_password_temporary
      parameters:
      - name: email
        in: query
        required: true
        description: Your email address.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: That email does not exist in the system.
      summary: Create a temporary access token for a user.  The user's password is not changed.
      tags:
      - user
  /user/password/temporary/{id}:
    get:
      operationId: user_checkTemporaryPassword_password_temporary_id
      parameters:
      - name: id
        in: path
        required: true
        description: The user ID to check.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: The token does not grant temporary access to the specified user.
      summary: Check if a specified token is a temporary access token for the specified user.  If the token is valid, returns information on the token and user.
      tags:
      - user
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The token to check.
              required:
              - token
  /user/verification:
    post:
      operationId: user_sendVerificationEmail_post_verification
      parameters:
      - name: login
        in: query
        required: true
        description: Your login or email address.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: That login is not registered.
      summary: Send verification email.
      tags:
      - user
  /user/{id}:
    delete:
      operationId: user_deleteUser_delete_id
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: You do not have permission to delete this user.
      summary: Delete a user by ID.
      tags:
      - user
    get:
      operationId: user_getUser_id
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: ID was invalid.
        '403':
          description: You do not have permission to see this user.
      summary: Get a user by ID.
      tags:
      - user
    put:
      operationId: user_updateUser_put_id
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      - name: firstName
        in: query
        required: true
        description: First name of the user.
        schema:
          type: string
      - name: lastName
        in: query
        required: true
        description: Last name of the user.
        schema:
          type: string
      - name: email
        in: query
        required: true
        description: The email of the user.
        schema:
          type: string
      - name: admin
        in: query
        required: false
        description: Is the user a site admin (admin access required)
        schema:
          type: boolean
      - name: status
        in: query
        required: false
        description: The account status (admin access required)
        schema:
          type: string
          enum:
          - pending
          - enabled
          - disabled
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '403':
          description: 'You do not have write access for this user.


            Must be an admin to create an admin.'
      summary: Update a user's information.
      tags:
      - user
  /user/{id}/details:
    get:
      operationId: user_getUserDetails_id_details
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '403':
          description: Read access was denied on the user.
      summary: Get detailed information about a user.
      tags:
      - user
  /user/{id}/otp:
    delete:
      operationId: user_removeOtp_delete_id_otp
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '403':
          description: Admin access was denied on the user.
      summary: Disable one-time passwords for this user.
      tags:
      - user
    post:
      operationId: user_initializeOtp_post_id_otp
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '403':
          description: Admin access was denied on the user.
      summary: Initiate the enablement of one-time passwords for this user.
      tags:
      - user
    put:
      operationId: user_finalizeOtp_put_id_otp
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      - name: Girder-OTP
        in: header
        required: true
        description: A one-time password for this user
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: A parameter was invalid.
        '403':
          description: Admin access was denied on the user.
      summary: Finalize the enablement of one-time passwords for this user.
      tags:
      - user
  /user/{id}/password:
    put:
      description: Only administrators may use this endpoint.
      operationId: user_changeUserPassword_put_id_password
      parameters:
      - name: id
        in: path
        required: true
        description: The ID of the document.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: The new password is invalid.
        '403':
          description: You are not an administrator.
      summary: Change a user's password.
      tags:
      - user
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                password:
                  type: string
                  format: password
                  description: The user's new password.
              required:
              - password
  /user/{id}/quota:
    get:
      operationId: user_getUserQuota_id_quota
      parameters:
      - name: id
        in: path
        required: true
        description: The user ID
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
      summary: Get quota and assetstore policies for the user.
      tags:
      - user
    put:
      operationId: user_setUserQuota_put_id_quota
      parameters:
      - name: id
        in: path
        required: true
        description: The user ID
        schema:
          type: string
      - name: policy
        in: query
        required: true
        description: A JSON object containing the policies.  This is a dictionary of keys and values.  Any key that is not specified does not change.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '400':
          description: ID was invalid.
        '403':
          description: Read permission denied on the user.
      summary: Set quota and assetstore policies for the user.
      tags:
      - user
  /user/{id}/verification:
    put:
      operationId: user_verifyEmail_put_id_verification
      parameters:
      - name: id
        in: path
        required: true
        description: The user ID to check.
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: The token is invalid or expired.
      summary: Verify an email address using a token.
      tags:
      - user
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: The token to check.
              required:
              - token
components:
  schemas:
    Token:
      type: object
    User:
      type: object
  securitySchemes:
    Girder-Token:
      in: header
      name: Girder-Token
      type: apiKey