swagger.yaml

# =============================================================================
# Copyright (c) 2016, salesforce.com, inc.
# All rights reserved.
# Licensed under the BSD 3-Clause license.
# For full license text, see LICENSE.txt file in the repo root or
# https://opensource.org/licenses/BSD-3-Clause
# =============================================================================

# =============================================================================
# api/v1/swagger.yaml
# =============================================================================
swagger: "2.0"

# =============================================================================
info:
  version: 1.0.0
  title: Refocus API
  description: >-
    Refocus is a platform for visualizing the health and status of systems
    and/or services under observation. Check out our
    [home page](https://salesforce.github.io/refocus),
    [docs](https://salesforce.github.io/refocus/docs/00-welcome) and
    [github](https://github.com/salesforce/refocus) repository.

    ### API Reference

    The Refocus API is a
    [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) API
    which allows client applications to interact with Refocus. We use standard
    HTTP response codes, standard HTTP authentication and
    standard HTTP verbs, all of which make it easy to integrate with lots of
    HTTP clients. JSON is returned by all API responses, including errors.
  termsOfService: >-
    [License](https://github.com/salesforce/refocus/blob/master/LICENSE.txt)
  contact:
    name: Salesforce Customer Experience Tools
    url: https://salesforce.github.io/refocus
    # email: focusapi@salesforce.com
  license:
    name: BSD 3-Clause
    url: https://github.com/salesforce/refocus/blob/master/LICENSE.txt

# =============================================================================
# host: localhost:10010

# =============================================================================
basePath: /v1

# =============================================================================
# externalDocs:
#   description: >-
#     Focus API Documentation
#   url: http://focus.salesforce.com/docs/api/

# =============================================================================
# schemes:
#   - https
#   - http

# =============================================================================
securityDefinitions:
  jwt:
    type: apiKey
    name: Authorization
    in: header
    description: >-
      Include an `Authorization` request header with your
      [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT) as the value.
      You can request a token from the UI (/tokens/new) or using API
      `POST /v1/tokens`. Never expose your secret API access token!

# =============================================================================
consumes:
  - application/json

# =============================================================================
produces:
  - application/json

# =============================================================================
paths:

  # ---------------------------------------------------------------------------
  /admin/sampleStore/rebuild:
    x-swagger-router-controller: admin
    post:
      security:
        - jwt: []
      summary: Rebuild redis sampleStore
      tags: [ admin ]
      description: >-
        Rebuild the redis sampleStore from the samples in the database.
        Requires user to have an admin profile.
      operationId: rebuildSampleStore
      responses:
        204:
          description: >-
            Success.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /aspects:
    x-swagger-router-controller: aspects
    get:
      security:
        - jwt: []
      summary: Find aspects
      tags: [ aspects ]
      description: >-
        Find an aspect or aspects. You may query using field filters with
        asterisk (*) wildcards. You may also optionally specify sort, limit,
        offset, and a list of fields to include in the response. The global
        default limit will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /aspects
        url: http://focus.salesforce.com/docs/api/aspects
      operationId: findAspects
      parameters:
        -
          $ref: "#/parameters/AspectsFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'.
            Prepend the field name with a minus sign to specify descending
            order, e.g. '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - description
              - helpEmail
              - helpUrl
              - id
              - isPublished
              - name
              - rank
              - timeout
              - valueLabel
              - valueType
              - createdAt
              - updatedAt
              - -description
              - -helpEmail
              - -helpUrl
              - -id
              - -isPublished
              - -name
              - -timeout
              - -valueLabel
              - -valueType
              - -createdAt
              - -rank
              - -updatedAt
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: name
          in: query
          description: >-
            Filter by aspect name; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: description
          in: query
          description: >-
            Filter by aspect description; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: imageUrl
          in: query
          description: >-
            Filter by aspect imageUrl; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: isPublished
          in: query
          description: >-
            Filter by aspect isPublished (true|false).
          required: false
          type: boolean
        -
          name: rank
          in: query
          description: >-
            Filter by aspect rank.
          required: false
          type: string
        -
          name: timeout
          in: query
          description: >-
            Filter by aspect timeout; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: valueLabel
          in: query
          description: >-
            Filter by aspect valueLabel; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: valueType
          in: query
          description: >-
            Filter by aspect valueType (BOOLEAN|NUMERIC|PERCENT).
          required: false
          type: string
        -
          name: status
          in: query
          description: >-
            Filter by aspect status.
          required: false
          type: string
        -
          name: tags
          in: query
          items:
            type: string
            maxLength: 60
            pattern: ^[0-9A-Za-z_-]{1,60}$
          description: >-
             Comma-separated list of tags to include/exclude. Tag names are
             case-insensitive. For example, ?tags=FOO,BAR will only return
             aspects with tags FOO and BAR. Prefix each of the tag name with
             a negative sign to indicate that a aspect with that tag should
             be excluded. For example, ?tags=-BAZ,FOO will return only the
             aspects with tag name not equal to BAZ or FOO. A mix of tag
             names with and without minus signs, for example ?tags=BAZ,-FOO
             are not allowed. Aspects without tags are not included in the
             include result set.
          type: array
          required: false
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when aspects were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when aspects were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, returns a list of aspects.
          schema:
            type: array
            items:
              $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create aspect
      tags: [ aspects ]
      description: >-
        Create a new aspect.
      operationId: postAspect
      parameters:
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: object
            description: A type of observation which can be measured.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the aspect. A lens may choose to display this
                  information to the user.
              helpEmail:
                type: string
                description: >
                  The email address where a user can go to get more help about the aspect.
                  A lens may choose to display this information to the user e.g. if the
                  user clicks a “help” icon attached to the aspect.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >
                  The url where a user can go to get more help about the aspect. A lens
                  may choose to display this information to the user e.g. if the user
                  clicks a “help” icon attached to the aspect.
              imageUrl:
                type: string
                maxLength: 2082
                description: Optional icon to represent the aspect.
              isPublished:
                type: boolean
                default: false
                description: >
                  This affects the visibility of samples; defaults to false. When set to
                  true, all the samples for this aspect are readable by other users; when
                  set to false, the samples for this aspect are only readable by the owner
                  of the aspect.
              name:
                type: string
                maxLength: 60
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              criticalRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Critical status.
              warningRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Warning status.
              infoRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Info status.
              okRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned OK status.
              timeout:
                type: string
                maxLength: 8
                pattern: ^[0-9]+[smhdSMHD]$
                description: >
                  The length of time after which a sample is treated as 'N/A', in the form
                  of /^[0-9]+[smhd]$/i. For example, use '5s' for five seconds, '2m' for
                  two minutes, '12h' for twelve hours, '1d' for one day.
              valueLabel:
                type: string
                maxLength: 10
                description: >
                  A short label the lens may display next to the value. Most useful to
                  specify a unit of measurement, e.g. 'ms' or '%'.
              valueType:
                type: string
                maxLength: 7
                enum:
                  - BOOLEAN
                  - NUMERIC
                  - PERCENT
                default: BOOLEAN
                description: >
                  The sample value must be able to be coerced to the specified data type.
                  This allows a lens to render sample data in different ways depending on
                  their type.
              tags:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-). Tag names cannot start with a dash (-).
              relatedLinks:
                type: array
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              rank:
                type: number
                description: >
                  Provide guidance for how a lens should display aspects--ascending order by
                  rank (numeric, nulls last) then within rank in ascending order by name
                  (alphanumeric).
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - timeout
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /aspects/{key}:
    x-swagger-router-controller: aspects
    delete:
      security:
        - jwt: []
      summary: Delete aspect
      tags: [ aspects ]
      description: >-
        Delete the specified aspect. Beware! Deleting an aspect also deletes all
        the samples associated with this aspect.
      operationId: deleteAspect
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the deleted aspect.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get aspect
      tags: [ aspects ]
      description: >-
        Retrieve the specified aspect by its id or name. You may also optionally
        specify a list of fields to include in the response.
      operationId: getAspect
      parameters:
        -
          name: key
          in: path
          description: The id or name of the aspect to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/AspectsFieldsParam"
      responses:
        200:
          description: Success, returns the specified aspect.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update aspect (partial)
      tags: [ aspects ]
      description: >-
        Update the specified aspect. If a field is not included in the query
        body, that field will not be updated.
      operationId: patchAspect
      parameters:
        -
          name: key
          in: path
          description: The id or name of the aspect to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Request body.
          required: true
          schema:
            type: object
            description: >
                  A type of observation which can be measured.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the aspect. A lens may choose to display this
                  information to the user.
              helpEmail:
                type: string
                description: >
                  The email address where a user can go to get more help about the aspect.
                  A lens may choose to display this information to the user e.g. if the
                  user clicks a “help” icon attached to the aspect.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >
                  The url where a user can go to get more help about the aspect. A lens
                  may choose to display this information to the user e.g. if the user
                  clicks a “help” icon attached to the aspect.
              imageUrl:
                type: string
                maxLength: 2082
                description: Optional icon to represent the aspect.
              isPublished:
                type: boolean
                default: false
                description: >
                  This affects the visibility of samples; defaults to false. When set to
                  true, all the samples for this aspect are readable by other users; when
                  set to false, the samples for this aspect are only readable by the owner
                  of the aspect.
              name:
                type: string
                maxLength: 60
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              criticalRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Critical status.
              warningRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Warning status.
              infoRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Info status.
              okRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned OK status.
              timeout:
                type: string
                maxLength: 10
                pattern: ^[0-9]{1,9}[smhdSMHD]$
                description: >
                  The length of time after which a sample is treated as 'N/A', in the form
                  of /^[0-9]+[smhd]$/i. For example, use '5s' for five seconds, '2m' for
                  two minutes, '12h' for twelve hours, '1d' for one day.
              valueLabel:
                type: string
                maxLength: 10
                description: >
                  A short label the lens may display next to the value. Most useful to
                  specify a unit of measurement, e.g. 'ms' or '%'.
              valueType:
                type: string
                maxLength: 7
                enum:
                  - BOOLEAN
                  - NUMERIC
                  - PERCENT
                default: BOOLEAN
                description: >
                  The sample value must be able to be coerced to the specified data type.
                  This allows a lens to render sample data in different ways depending on
                  their type.
              tags:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-). Tag names cannot start with a dash (-).
              relatedLinks:
                type: array
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              rank:
                type: number
                description: >
                  Provide guidance for how a lens should display aspects--ascending order by
                  rank (numeric, nulls last) then within rank in ascending order by name
                  (alphanumeric).
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: Success, returns the updated aspect.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/404"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update aspect (full)
      tags: [ aspects ]
      description: >-
        Update the specified aspect. If a field is not included in the query
        body, that field will be set to null (or false or empty or a default
        enum value).
      operationId: putAspect
      parameters:
        -
          name: key
          in: path
          description: The id or name of the aspect to update
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Request body
          required: true
          schema:
            type: object
            description: A type of observation which can be measured.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the aspect. A lens may choose to display this
                  information to the user.
              helpEmail:
                type: string
                description: >
                  The email address where a user can go to get more help about the aspect.
                  A lens may choose to display this information to the user e.g. if the
                  user clicks a “help” icon attached to the aspect.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >
                  The url where a user can go to get more help about the aspect. A lens
                  may choose to display this information to the user e.g. if the user
                  clicks a “help” icon attached to the aspect.
              imageUrl:
                type: string
                maxLength: 2082
                description: >
                  Optional icon to represent the aspect.
              isPublished:
                type: boolean
                default: false
                description: >
                  This affects the visibility of samples; defaults to false. When set to
                  true, all the samples for this aspect are readable by other users; when
                  set to false, the samples for this aspect are only readable by the owner
                  of the aspect.
              name:
                type: string
                maxLength: 60
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              criticalRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Critical status.
              warningRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Warning status.
              infoRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned Info status.
              okRange:
                type: array
                items:
                  type: number
                maxLength: 2
                minLength: 2
                example: [1,7]
                description: >
                  A two-element array of type decimal. Determines what range of values
                  should be assigned OK status.
              timeout:
                type: string
                maxLength: 8
                pattern: ^[0-9]+[smhdSMHD]$
                description: >
                  The length of time after which a sample is treated as 'N/A', in the form
                  of /^[0-9]+[smhd]$/i. For example, use '5s' for five seconds, '2m' for
                  two minutes, '12h' for twelve hours, '1d' for one day.
              valueLabel:
                type: string
                maxLength: 10
                description: >
                  A short label the lens may display next to the value. Most useful to
                  specify a unit of measurement, e.g. 'ms' or '%'.
              valueType:
                type: string
                maxLength: 7
                enum:
                  - BOOLEAN
                  - NUMERIC
                  - PERCENT
                default: BOOLEAN
                description: >
                  The sample value must be able to be coerced to the specified data type.
                  This allows a lens to render sample data in different ways depending on
                  their type.
              tags:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-). Tag names cannot start with a dash (-).
              relatedLinks:
                type: array
                default: []
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              rank:
                type: number
                description: >
                  Provide guidance for how a lens should display aspects--ascending order by
                  rank (numeric, nulls last) then within rank in ascending order by name
                  (alphanumeric).
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
      responses:
        200:
          description: >-
            Success, returns the updated aspect.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /aspects/{key}/tags:
    x-swagger-router-controller: aspects
    delete:
      security:
        - jwt: []
      summary: Delete aspect tags
      tags: [ aspects ]
      description: >-
        Delete all the tags of the specified aspect.
      operationId: deleteAspectTags
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect for which all the tags need to be
            deleted.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the updated aspect.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /aspects/{key}/tags/{tagName}:
    x-swagger-router-controller: aspects
    delete:
      security:
        - jwt: []
      summary: Delete aspect tag
      tags: [ aspects ]
      description: >-
        Delete the specified tag of the aspect.
      operationId: deleteAspectTags
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect for which specified tag needs to be
            deleted.
          required: true
          type: string
        -
          name: tagName
          in: path
          description: >-
            The name of the tag to be deleted
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the updated aspect after deleting tag.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /aspects/{key}/relatedLinks:
    x-swagger-router-controller: aspects
    delete:
      security:
        - jwt: []
      summary: Delete aspect related links
      tags: [ aspects ]
      description: >-
        Deletes all the related links of the specified aspect.
      operationId: deleteAspectRelatedLinks
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect for which all the related links need
            to be deleted.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the updated aspect.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /aspects/{key}/relatedLinks/{relName}:
    x-swagger-router-controller: aspects
    delete:
      security:
        - jwt: []
      summary: Delete aspect related link
      tags: [ aspects ]
      description: >-
        Delete the specified related link of the aspect.
      operationId: deleteAspectRelatedLinks
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect for which specified related link needs
            to be deleted.
          required: true
          type: string
        -
          name: relName
          in: path
          description: >-
            The name of the relatedLink to delete
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the updated aspect.
          schema:
            $ref: "#/definitions/AspectsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /aspects/{key}/writers:
    x-swagger-router-controller: aspects
    delete:
      security:
        - jwt: []
      summary: Delete aspect writers
      tags: [ aspects ]
      description: >-
        Remove all users from an aspect’s list of authorized writers.
      operationId: deleteAspectWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the aspect.
          required: true
          type: string
      responses:
        204:
          description: >-
            The aspect is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get aspect writers
      tags: [ aspects ]
      description: >-
        Get the list of all authorized writers for an aspect.
      operationId: getAspectWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the aspect.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the aspect
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add aspect writer
      tags: [ aspects ]
      description: >-
        Add one or more users to an aspect’s list of authorized writers.
      operationId: postAspectWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name or id
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/AspectWriterResponse"
              description: >-
                The users having write permission to the aspect
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

# ---------------------------------------------------------------------------
  /aspects/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: aspects
    delete:
      security:
        - jwt: []
      summary: Delete aspect writer
      tags: [ aspects ]
      description: >-
        Remove a user from an aspect’s list of authorized writers.
      operationId: deleteAspectWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the aspect.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get aspect writer
      tags: [ aspects ]
      description: >-
        Determine whether a user is an authorized writer for an aspect.
      operationId: getAspectWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /auditEvents:
    x-swagger-router-controller: auditEvents
    get:
      security:
        - jwt: []
      summary: Find auditEvents
      tags: [ auditEvents ]
      description: >-
        Find auditEvents. You may query using field filters with asterisk (*)
        wildcards. You may also optionally specify sort, limit, offset, and a
        list of fields to include in the response.
      externalDocs:
        description: >-
          GET /auditEvents
        url: http://focus.salesforce.com/docs/api/auditEvents
      operationId: findAuditEvents
      parameters:
        -
          $ref: "#/parameters/AuditEventsFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g.
            '...?sort=loggedAt'. Prepend the field name with a minus sign
            to specify descending order, e.g. '...?sort=-loggedAt'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - createdAt
              - id
              - isError
              - loggedAt
              - resourceName
              - resourceType
              - -createdAt
              - -id
              - -isError
              - -loggedAt
              - -resourceName
              - -resourceType
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: startAt
          in: query
          description: >-
            Filter by auditEvent loggedAt timestamp range
            (https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14).
            Cannot combine startAt/endAt with relativeDateTime.
          required: false
          type: string
        -
          name: endAt
          in: query
          description: >-
            Filter by auditEvent loggedAt timestamp range
            (https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14).
            Cannot combine startAt/endAt with relativeDateTime.
          required: false
          type: string
        -
          name: relativeDateTime
          in: query
          description: >-
            Filter by auditEvent loggedAt timestamp using relative date/time,
            e.g. "-12h" for the last twelve hours, "-15m" for the last fifteen
            minutes, etc. Cannot combine startAt/endAt with relativeDateTime.
          required: false
          type: string
        -
          name: resourceType
          in: query
          description: >-
            Filter by auditEvent resourceType; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: resourceName
          in: query
          description: >-
            Filter by auditEvent resourceName; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: isError
          in: query
          description: >-
            Filter by auditEvent isError.
          required: false
          type: boolean
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when AuditEvents were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when AuditEvents were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, returns a list of auditEvents.
          schema:
            type: array
            items:
              $ref: "#/definitions/AuditEventsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create new auditEvents
      tags: [ auditEvents ]
      description: >-
        Create new auditEvents.
      operationId: postAuditEvents
      parameters:
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: object
              description: >
                An auditable Refocus event.
              properties:
                details:
                  type: object
                  description: >
                    A JSON object with additional event details.
                loggedAt:
                  type: string
                  description: >
                    The timestamp when the event was logged.
                isError:
                  type: boolean
                  default: false
                  description: >
                    True if this auditEvent represents an error.
                resourceName:
                  type: string
                  maxLength: 4096
                  description: >
                    The name of the resource associated with this event.
                resourceType:
                  type: string
                  maxLength: 4096
                  description: >
                    The type of the resource associated with this event, e.g.
                    "Collector", "Subject", etc.
              required:
                - resourceType
                - resourceName
      responses:
        200:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/BulkUpsertResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /auditEvents/{key}:
    x-swagger-router-controller: auditEvents
    get:
      security:
        - jwt: []
      summary: Get auditEvent
      tags: [ auditEvents ]
      description: >-
        Retrieve the specified auditEvent by its id. You may also optionally
        specify a list of fields to include in the response.
      operationId: getAuditEvent
      parameters:
        -
          name: key
          in: path
          description: The id of the auditEvent to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/AuditEventsFieldsParam"
      responses:
        200:
          description: Success, returns the specified auditEvent.
          schema:
            $ref: "#/definitions/AuditEventsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /authenticate:
    x-swagger-router-controller: authenticate
    post:
      summary: Authenticate user
      tags: [ authenticate ]
      description: >-
        Authenticate a user with username and password.
      operationId: authenticateUser
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              Credentials of person who interacts with the Refocus system.
            properties:
              username:
                type: string
                maxLength: 254
                description: >
                  The User name provided by the user during registeration
              password:
                type: string
                format: password
                description: >
                  The user's password.
            required:
              - username
              - password
      responses:
        200:
          description: >-
            Authenticated the user.
          schema:
            $ref: "#/definitions/AuthenticationResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botActions:
    x-swagger-router-controller: botActions
    get:
      security:
        - jwt: []
      summary: Find botActions
      tags: [ botActions ]
      operationId: findBotActions
      parameters:
        -
          name: roomId
          description: Get actions from specific room
          in: query
          required: false
          type: integer
        -
          name: botId
          description: Get actions from specific bot
          in: query
          required: true
          type: string
        -
          name: name
          description: Get botActions by name
          in: query
          required: false
          type: string
        -
          name: isPending
          description: Get pending botActions
          in: query
          required: false
          type: boolean
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when BotActions were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when BotActions were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns all BotActions
          schema:
            type: array
            items:
              $ref: "#/definitions/BotActionResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    post:
      security:
        - jwt: []
      summary: Create botAction
      tags: [ botActions ]
      description: Create a new botAction with a name, room id and bot id
      operationId: postBotActions
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Create botAction properties
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the botAction
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              isPending:
                type: boolean
                description: If the botAction is active
              parameters:
                type: array
                description: Array of objects that contain the name of actions a botAction can take and an array of parameters needed for that action
                items:
                  type: object
              response:
                type: object
                description: A JSON field that contains the output of an action
              roomId:
                type: integer
                description: The room in which this action is in reference with
              botId:
                type: string
                description: The bot of which this action is in reference with
              userId:
                type: string
                description: The user of which this action is in reference with
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - roomId
              - botId
      responses:
        201:
          description: >-
            Created botAction
          schema:
            $ref: "#/definitions/BotActionResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botActions/{key}:
    x-swagger-router-controller: botActions
    delete:
      security:
        - jwt: []
      summary: Delete botAction
      tags: [ botActions ]
      description: >-
        Delete a specific botAction
      operationId: deleteBotActions
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botAction to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, Deleted BotAction
          schema:
            $ref: "#/definitions/BotActionResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    get:
      security:
        - jwt: []
      summary: Get botAction
      tags: [ botActions ]
      operationId: getBotAction
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botAction to retrieve
          required: true
          type: string
        -
          name: isPending
          description: Get botActions depending on its pending tag
          in: query
          required: false
          type: boolean
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns specified botAction
          schema:
            $ref: "#/definitions/BotActionResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    patch:
      security:
        - jwt: []
      summary: Update botAction (partial)
      tags: [ botActions ]
      description: Update botAction fields
      operationId: patchBotAction
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botAction to retrieve
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Update specified botAction fields
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the botAction
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              isPending:
                type: boolean
                description: If the botAction is active
              parameters:
                type: array
                description: Array of objects that contain the name of actions a botAction can take and an array of parameters needed for that action
                items:
                  type: object
              response:
                type: object
                description: A JSON field that contains the output of an action
              roomId:
                type: integer
                description: The room in which this action is in reference with
              botId:
                type: string
                description: The bot of which this action is in reference with
              userId:
                type: string
                description: The user of which this action is in reference with
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Updated field
          schema:
            $ref: "#/definitions/BotActionResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botActions/{key}/writers:
    x-swagger-router-controller: botActions
    delete:
      security:
        - jwt: []
      summary: Delete bot writers
      tags: [ botActions ]
      description: >-
        Remove all users from a botAction's list of authorized writers.
      operationId: deleteBotActionsWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the bot.
          required: true
          type: string
      responses:
        204:
          description: >-
            The bot is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get botAction writers
      tags: [ botActions ]
      description: >-
        Get the list of all authorized writers for a botAction.
      operationId: getBotActionWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botAction for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the botAction.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the botAction
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add botAction writer
      tags: [ botActions ]
      description: >-
        Add one or more users to a botActions list of authorized writers.
      operationId: postBotActionWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botAction for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/BotActionWriterResponse"
              description: >-
                The users having write permission to the botAction
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botActions/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: botActions
    delete:
      security:
        - jwt: []
      summary: Delete botActions writer
      tags: [ botActions ]
      description: >-
        Remove a user from a botAction's list of authorized writers.
      operationId: deleteBotWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botAction
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the botAction.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get bot writer
      tags: [ botActions ]
      description: >-
        Determine whether a user is an authorized writer for botAction.
      operationId: getBotActionWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botAction for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botData:
    x-swagger-router-controller: botData
    get:
      security:
        - jwt: []
      tags: [ botData ]
      operationId: findBotData
      parameters:
        -
          name: roomId
          description: Get data from specific room
          in: query
          required: false
          type: integer
        -
          name: botId
          description: Get data from specific bot
          in: query
          required: true
          type: string
        -
          name: name
          description: Filter botData by name
          in: query
          required: false
          type: string
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when BotData was created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when BotData was updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns all botData
          schema:
            type: array
            items:
              $ref: "#/definitions/BotDataResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    post:
      security:
        - jwt: []
      summary: Create botData
      tags: [ botData ]
      description: Create new bot data for a rooms specific bots
      operationId: postBotData
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Create botData properties
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the bot data
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              value:
                type: string
                description: Value of the bot data
              botId:
                type: string
                maxLength: 254
                description: UUID for the corresponding bot
              roomId:
                type: integer
                maxLength: 254
                description: Number for the corresponding room
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - value
              - roomId
              - botId
      responses:
        201:
          description: >-
            Created botData
          schema:
            $ref: "#/definitions/BotDataResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botData/{key}/writers:
    x-swagger-router-controller: botData
    delete:
      security:
        - jwt: []
      summary: Delete bot writers
      tags: [ botData ]
      description: >-
        Remove all users from a botData's list of authorized writers.
      operationId: deleteBotDataWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the botData.
          required: true
          type: string
      responses:
        204:
          description: >-
            The botData is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get botData writers
      tags: [ botData ]
      description: >-
        Get the list of all authorized writers for a botData.
      operationId: getBotDataWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botData for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the botData.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the botData
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add botData writer
      tags: [ botData ]
      description: >-
        Add one or more users to a botDatas list of authorized writers.
      operationId: postBotDataWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botData for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/BotDataWriterResponse"
              description: >-
                The users having write permission to the botData
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botData/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: botData
    delete:
      security:
        - jwt: []
      summary: Delete botActions writer
      tags: [ botActions ]
      description: >-
        Remove a user from a botData's list of authorized writers.
      operationId: deleteBotDataWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botData
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the botAction.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get botData writer
      tags: [ botData ]
      description: >-
        Determine whether a user is an authorized writer for botData.
      operationId: getBotDataWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botData for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botData/upsert:
    x-swagger-router-controller: botData
    post:
      security:
        - jwt: []
      summary: Upsert botData
      tags: [ botData ]
      description: Creates or updates bot data for a room's specific bots
      operationId: upsertBotData
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Create botData properties
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the bot data
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              value:
                type: string
                description: Value of the bot data
              botId:
                type: string
                maxLength: 254
                description: UUID for the corresponding bot
              roomId:
                type: integer
                maxLength: 254
                description: Number for the corresponding room
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - value
              - roomId
              - botId
      responses:
        201:
          description: >-
            Bot Data Created
          schema:
            $ref: "#/definitions/BotDataResponse"
        200:
          description: >-
            Bot Data Updated
          schema:
            $ref: "#/definitions/BotDataResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /botData/{key}:
    x-swagger-router-controller: botData
    get:
      security:
        - jwt: []
      summary: Get botData
      tags: [ botData ]
      operationId: getBotData
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botData to retrieve
          required: true
          type: string
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns specified botData
          schema:
            $ref: "#/definitions/BotDataResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"


    patch:
      security:
        - jwt: []
      summary: Update botData (partial)
      tags: [ botData ]
      description: Update botData fields
      operationId: patchBotData
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botData to retrieve
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Create botData properties
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the bot data
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              value:
                type: string
                description: Value of the bot data
              botId:
                type: string
                maxLength: 254
                description: UUID for the coresponding bot
              roomId:
                type: integer
                maxLength: 254
                description: Number for the coresponding room
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Updated field
          schema:
            $ref: "#/definitions/BotDataResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

    delete:
      security:
        - jwt: []
      summary: Delete botData
      tags: [ botData ]
      description: >-
        Delete a specific botData
      operationId: deleteBotData
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the botData to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, Deleted BotData
          schema:
            $ref: "#/definitions/BotDataResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /bots:
    x-swagger-router-controller: bots
    get:
      security:
        - jwt: []
      summary: Find bots
      tags: [ bots ]
      operationId: findBots
      parameters:
        -
          name: name
          description: Get bots by name
          in: query
          required: false
          type: string
        -
          name: active
          description: Get active bots
          in: query
          required: false
          type: boolean
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when Bots were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when Bots were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns all Bots
          schema:
            type: array
            items:
              $ref: "#/definitions/BotResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    post:
      security:
        - jwt: []
      summary: Create bot
      tags: [ bots ]
      description: Create a new bot with a name
      operationId: postBots
      consumes:
        - multipart/form-data
      parameters:
        -
          name: name
          in: formData
          description: The unique readable name for the bot
          type: string
          required: true
          pattern: ^[0-9A-Za-z_\\-]{0,60}$
        -
          name: active
          in: formData
          description: Flag for if a bot is active with communication
          type: boolean
          default: false
        -
          name: url
          in: formData
          description: The URL of the code repository
          type: string
        -
          name: helpUrl
          in: formData
          description: The URL of the support documentation
          type: string
          required: false
        -
          name: ownerUrl
          in: formData
          description: The URL of the owner of the bot
          type: string
          required: false
        -
          name: ui
          description: The zipped HTML and Javascript needed to run the UI of the bot
          in: formData
          type: file
          format: binary
        -
          name: version
          in: formData
          description: The version of the bot. Use Semantic Versioning 2.0.0
          type: string
          required: true
        -
          name: displayName
          in: formData
          description: The name displayed in the bot header.
          type: string
          maxLength: 60
          required: false
        -
          name: actions
          in: formData
          description: Array of objects that contain the name of actions a bot can take and an array of parameters needed for that action
          type: array
          items:
            type: string
          default: []
        -
          name: data
          in: formData
          description: Array of objects that contain the name of data on a bot
          type: array
          items:
            type: string
          default: []
        -
          name: owner
          in: formData
          description: >
            The name of the user to assign as the owner. Defaults to the user that created it
          type: string
      responses:
        201:
          description: >-
            Created bot
          schema:
            $ref: "#/definitions/BotResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /bots/{key}:
    x-swagger-router-controller: bots
    delete:
      security:
        - jwt: []
      summary: Delete bot
      tags: [ bots ]
      description: >-
        Delete a specific bot
      operationId: deleteBot
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the bot to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, Deleted Bot
          schema:
            $ref: "#/definitions/BotResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    get:
      security:
        - jwt: []
      summary: Get bot
      tags: [ bots ]
      operationId: getBot
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the bot to retrieve
          required: true
          type: string
        -
          name: name
          description: Get bot by name
          in: query
          required: false
          type: string
        -
          name: active
          description: Get bots depending on its active tag
          in: query
          required: false
          type: boolean
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns specified bot
          schema:
            $ref: "#/definitions/BotResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    patch:
      security:
        - jwt: []
      summary: Update bot (partial)
      tags: [ bots ]
      description: Update bot fields
      operationId: patchBot
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the bot to retrieve
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Update specified bot fields
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the bot
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              url:
                type: string
                description: Bot url
              helpUrl:
                type: string
                description: Url of the support documentation for the bot
              ownerUrl:
                type: string
                description: Url of the owner of the bot
              active:
                type: boolean
                description: If the bot is active
              version:
                type: string
                description: The version of the bot. Use Semantic Versioning 2.0.0
              displayName:
                type: string
                maxLength: 60
                description: The name displayed in the bot header.
              actions:
                type: array
                description: Array of objects that contain the name of actions a bot can take and an array of parameters needed for that action
                items:
                  type: object
              data:
                type: array
                description: Array of objects that contain the name of data on a bot
                items:
                  type: object
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Updated field
          schema:
            $ref: "#/definitions/BotResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

    put:
      security:
        - jwt: []
      summary: Upgrade bot (full)
      tags: [ bots ]
      description: This route is used to update all the fields in a bot and to load in a new UI
      operationId: putBots
      consumes:
        - multipart/form-data
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the bot to retrieve
          required: true
          type: string
        -
          name: name
          in: formData
          description: The unique readable name for the bot
          type: string
          pattern: ^[0-9A-Za-z_\\-]{0,60}$
        -
          name: active
          in: formData
          description: Flag for if a bot is active with communication
          type: boolean
          default: false
        -
          name: url
          in: formData
          description: The URL of the bot server
          type: string
        -
          name: helpUrl
          in: formData
          description: The URL of the support documentation
          type: string
        -
          name: ownerUrl
          in: formData
          description: The URL of the owner of the bot
          type: string
        -
          name: version
          in: formData
          description: The version of the bot. Use Semantic Versioning 2.0.0
          type: string
        -
          name: displayName
          in: formData
          description: The name displayed in the bot header.
          type: string
          maxLength: 60
        -
          name: ui
          description: The zipped HTML and Javascript needed to run the UI of the bot
          in: formData
          type: file
          format: binary
        -
          name: actions
          in: formData
          description: Array of objects that contain the name of actions a bot can take and an array of parameters needed for that action
          type: array
          items:
            type: string
          default: []
        -
          name: data
          in: formData
          description: Array of objects that contain the name of data on a bot
          type: array
          items:
            type: string
          default: []
        -
          name: owner
          in: formData
          description: >
            The name of the user to assign as the owner. Defaults to the user that created it
          type: string
      responses:
        200:
          description: Success, returns the updated bot.
          schema:
            $ref: "#/definitions/BotResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------

  /bots/{key}/heartbeat:
    x-swagger-router-controller: bots
    post:
      security:
        - jwt: []
      summary: Send heartbeat
      tags: [ bots ]
      description: >-
        Send heartbeat.
      operationId: heartbeat
      parameters:
        -
          name: key
          in: path
          description: Key/Name of bot.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >-
              Heartbeat from the refocus.
            properties:
              timestamp:
                type: integer
      responses:
        200:
          description: Success.
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"

  # ---------------------------------------------------------------------------
  /bots/{key}/writers:
    x-swagger-router-controller: bots
    delete:
      security:
        - jwt: []
      summary: Delete bot writers
      tags: [ bots ]
      description: >-
        Remove all users from a bot's list of authorized writers.
      operationId: deleteBotWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the bot.
          required: true
          type: string
      responses:
        204:
          description: >-
            The bot is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get bot writers
      tags: [ bots ]
      description: >-
        Get the list of all authorized writers for a bot.
      operationId: getBotWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the bot for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the bot.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the subject
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add bot writer
      tags: [ bots ]
      description: >-
        Add one or more users to a bots list of authorized writers.
      operationId: postBotWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the bot for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/BotWriterResponse"
              description: >-
                The users having write permission to the subject
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /bots/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: bots
    delete:
      security:
        - jwt: []
      summary: Delete bot writer
      tags: [ bots ]
      description: >-
        Remove a user from a subjects's list of authorized writers.
      operationId: deleteBotWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the bot
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the subject.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get bot writer
      tags: [ bots ]
      description: >-
        Determine whether a user is an authorized writer for bot.
      operationId: getBotWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the bot for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /collectors:
    x-swagger-router-controller: collectors
    get:
      security:
        - jwt: []
      tags: [ collectors ]
      summary: Find collectors
      description: >-
        Find a collector or collectors. You may query using field filters with
        asterisk (*) wildcards. You may also optionally specify sort, limit,
        offset, and a list of fields to include in the response. The global
        default limit will apply if no limit param is specified.
      operationId: findCollectors
      parameters:
        -
          $ref: "#/parameters/CollectorFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - name
              - status
              - registered
              - lastHeartbeat
              - lastModifiedAt
              - createdBy
              - lastUpdatedBy
              - helpEmail
              - helpUrl
              - host
              - ipAddress
              - version
              - -name
              - -status
              - -registered
              - -lastHeartbeat
              - -lastModifiedAt
              - -createdBy
              - -lastUpdatedBy
              - -helpEmail
              - -helpUrl
              - -host
              - -ipAddress
              - -version
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: name
          in: query
          description: >-
            Filter by name; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: status
          in: query
          description: >-
            Filter by status; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: registered
          in: query
          description: >-
            Filter by registered (true|false).
          required: false
          type: boolean
        -
          name: helpEmail
          in: query
          description: >-
            Filter by helpEmail; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: helpUrl
          in: query
          description: >-
            Filter by helpUrl; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: host
          in: query
          description: >-
            Filter by host; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: version
          in: query
          description: >-
            Filter by version; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when collectors were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when collectors were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: Success, returns an array of zero or more Refocus collectors.
          schema:
            type: "array"
            items:
              $ref: "#/definitions/CollectorResponse"

  # ---------------------------------------------------------------------------

  /collectors/start:
    x-swagger-router-controller: collectors
    post:
      security:
        - jwt: []
      parameters:
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: object
            description: Access restricted to Refocus Collector only.
            properties:
              name:
                type: string
                description: Access restricted to Refocus Collector only.
              description:
                type: string
                maxLength: 4096
                description: Access restricted to Refocus Collector only.
              helpEmail:
                type: string
                description: Access restricted to Refocus Collector only.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: Access restricted to Refocus Collector only.
              host:
                type: string
                description: Access restricted to Refocus Collector only.
                maxLength: 4096
              ipAddress:
                type: string
                description: Access restricted to Refocus Collector only.
                maxLength: 60
              osInfo:
                type: object
                description: Access restricted to Refocus Collector only.
              processInfo:
                type: object
                description: Access restricted to Refocus Collector only.
              version:
                type: string
                description: Access restricted to Refocus Collector only.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - version
      summary: Start collector
      tags: [ collectors ]
      description: Starts the specified collector.
      operationId: startCollector

      responses:
        200:
          description: Success, returns the specified collector's metadata.
          schema:
            $ref: "#/definitions/CollectorResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"

  # ---------------------------------------------------------------------------

  /collectors/{key}:
    x-swagger-router-controller: collectors
    get:
      security:
        - jwt: []
      tags: [ collectors ]
      summary: Get collector
      description: >-
        Retrieve the specified collector metadata by the collector's id or name.
        You may also optionally specify a list of fields to include in the response.
      operationId: getCollector
      parameters:
        -
          name: key
          in: path
          description: The id or name of the collector to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/CollectorFieldsParam"
      responses:
        200:
          description: Success, returns the specified collector's metadata.
          schema:
            $ref: "#/definitions/CollectorResponse"
        400:
          description: "Invalid ID supplied"
        404:
          description: "Collector not found"
    patch:
      security:
        - jwt: []
      tags: [ collectors ]
      summary: Update collector (partial)
      description: >-
        Update the specified collector's config data. If a field is not included
        in the querybody, that field will not be updated.
      operationId: patchCollector
      parameters:
        -
          name: key
          in: path
          description: The id or name of the collector to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Request body.
          required: true
          schema:
            type: object
            description: Fields permitted for patching.
            properties:
              collectorGroup:
                description: Name of the collectorGroup this collector belongs to.
                type: string
              description:
                type: string
                maxLength: 4096
                description: >
                  Describes this Collector; helps a user determine which Collectors they should assign to run their collection.
              helpEmail:
                type: string
                description: >
                  The email address where a user can go to get more help about the collector.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >
                  The url where a user can go to get more help about the collector.
              host:
                type: string
                description: Access restricted to Refocus Collector only.
                maxLength: 4096
              ipAddress:
                type: string
                description: Access restricted to Refocus Collector only.
                maxLength: 60
              osInfo:
                type: object
                description: Access restricted to Refocus Collector only.
              processInfo:
                type: object
                description: Access restricted to Refocus Collector only.
              version:
                type: string
                description: Access restricted to Refocus Collector only.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"

  # ---------------------------------------------------------------------------

  /collectors/{key}/status:
    x-swagger-router-controller: collectors
    get:
      security:
        - jwt: []
      tags: [ collectors ]
      summary: Get collector status
      description: >-
        Retrieve the specified collector status by the collector's id or name.
      operationId: getCollectorStatus
      parameters:
        -
          name: key
          in: path
          description: The id or name of the collector to get the status of.
          required: true
          type: string
      responses:
        200:
          description: Success, returns the specified collector's status.
          schema:
             type: object
             properties:
               status:
                 type: string
                 description: The collector status.
        400:
          description: "Invalid ID supplied"
        404:
          description: "Collector not found"

  # ---------------------------------------------------------------------------

  /collectors/{key}/deregister:
    x-swagger-router-controller: collectors
    post:
      security:
        - jwt: []
      summary: Deregister collector
      tags: [ collectors ]
      description: >-
        Deregister the specified collector.
      operationId: deregisterCollector
      parameters:
        -
          name: key
          in: path
          description: Deregister the specified collector.
          required: true
          type: string
      responses:
        200:
          description: Success, returns the specified collector's metadata.
          schema:
            $ref: "#/definitions/CollectorResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"

  # ---------------------------------------------------------------------------

  /collectors/{key}/reregister:
    x-swagger-router-controller: collectors
    post:
      security:
        - jwt: []
      summary: Reregisters a deregistered collector
      tags: [ collectors ]
      description: >-
        Reregister the specified collector.
      operationId: reregisterCollector
      parameters:
        -
          name: key
          in: path
          description: Reregister the specified collector.
          required: true
          type: string
      responses:
        200:
          description: Success, returns the specified collector's metadata.
          schema:
            $ref: "#/definitions/CollectorResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"

  # ---------------------------------------------------------------------------

  /collectors/{key}/heartbeat:
    x-swagger-router-controller: collectors
    post:
      security:
        - jwt: []
      summary: Send heartbeat
      tags: [ collectors ]
      description: >-
        Send heartbeat. Access restricted to Refocus Collector only.
      operationId: heartbeat
      parameters:
        -
          name: key
          in: path
          description: Access restricted to Refocus Collector only.
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Access restricted to Refocus Collector only.
          required: true
          schema:
            type: object
            description: >-
              Heartbeat from the collector.
            properties:
              timestamp:
                type: integer
                description: Access restricted to Refocus Collector only.
              collectorConfig:
                type: object
                properties:
                  osInfo:
                    type: object
                    properties:
                      arch:
                        type: string
                        description: Access restricted to Refocus Collector only.
                      hostname:
                        type: string
                        description: Access restricted to Refocus Collector only.
                      platform:
                        type: string
                        description: Access restricted to Refocus Collector only.
                      release:
                        type: string
                        description: Access restricted to Refocus Collector only.
                      type:
                        type: string
                        description: Access restricted to Refocus Collector only.
                      username:
                        type: string
                        description: Access restricted to Refocus Collector only.
                  processInfo:
                    type: object
                    properties:
                      execPath:
                        type: string
                        description: Access restricted to Refocus Collector only.
                      memoryUsage:
                        type:  object
                        description: Access restricted to Refocus Collector only.
                      uptime:
                        type: number
                        description: Access restricted to Refocus Collector only.
                      version:
                        type: string
                        description: Access restricted to Refocus Collector only.
                      versions:
                        type: object
                        description: Access restricted to Refocus Collector only.
                  version:
                    type: string
                    description: Access restricted to Refocus Collector only.
      responses:
        200:
          description: Success.
          schema:
            $ref: "#/definitions/HeartbeatResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"

  # ---------------------------------------------------------------------------

  /collectors/{key}/stop:
    x-swagger-router-controller: collectors
    post:
      security:
        - jwt: []
      summary: Stop collector
      tags: [ collectors ]
      description: >-
        Change collector status from Running to Stopped. Invalid if the
        collector's status is already stopped.
      operationId: stopCollector
      parameters:
        -
          name: key
          in: path
          description: The id or name of the collector to stop.
          required: true
          type: string
      responses:
        200:
          description: Success, returns the specified collector's metadata.
          schema:
            $ref: "#/definitions/CollectorResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"

  # ---------------------------------------------------------------------------

  /collectors/{key}/pause:
    x-swagger-router-controller: collectors
    post:
      security:
        - jwt: []
      summary: Pause running collector
      tags: [ collectors ]
      description: >-
        Change collector status from Running to Paused. Invalid if the
        collector's status is not Running.
      operationId: pauseCollector
      parameters:
        -
          name: key
          in: path
          description: The id or name of the collector to pause.
          required: true
          type: string
      responses:
        200:
          description: Success, returns the specified collector's metadata.
          schema:
            $ref: "#/definitions/CollectorResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"

  # ---------------------------------------------------------------------------

  /collectors/{key}/resume:
    x-swagger-router-controller: collectors
    post:
      security:
        - jwt: []
      summary: Resume paused collector
      tags: [ collectors ]
      description: >-
        Change collector status from Paused to Running. Invalid if the
        collector's status is not Paused.
      operationId: resumeCollector
      parameters:
        -
          name: key
          in: path
          description: The id or name of the collector to resume.
          required: true
          type: string
      responses:
        200:
          description: Success, returns the specified collector's metadata.
          schema:
            $ref: "#/definitions/CollectorResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"

  # ---------------------------------------------------------------------------

  /collectors/{key}/writers:
    x-swagger-router-controller: collectors
    delete:
      security:
        - jwt: []
      summary: Delete collector writers
      tags: [ collectors ]
      description: >-
        Remove all users from a collector’s list of authorized writers.
      operationId: deleteCollectorWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the collector.
          required: true
          type: string
      responses:
        204:
          description: >-
            The collector is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get collector writers
      tags: [ collectors ]
      description: >-
        Returns a list of users permitted to modify this collector. DOES NOT
        use wildcards.
      operationId: getCollectorWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the collector for which the authorized list of
            users are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns The users having write permission to the collector
            metadata.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the collector metadata.
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add collector writer
      tags: [ collectors ]
      description: >-
         Add one or more users to a collector's list of authorized writers.
      operationId: postCollectorWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the collector for which the authorized list of
            users are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name or id
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized
            writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/CollectorWriterResponse"
              description: >-
                The users who have write permission to the collector metadata.
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------

  /collectors/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: collectors
    get:
      security:
        - jwt: []
      tags: [ collectors ]
      summary: Get collector writers
      description: >-
        Determine whether a user is an authorized writer for a Collector.
        If user is unauthorized, there is no writer by this name for this
        collector.
      operationId: getCollectorWriter
      parameters:
      -
        name: key
        in: path
        description: The id or name of the collector
        required: true
        type: string
      - name: userNameOrId
        in: "path"
        description: The id or name of the user
        required: true
        type: string
      responses:
        200:
          description: Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        404:
          description: userNameOrId does not identify a User
    delete:
      security:
        - jwt: []
      summary: Delete collector writer
      tags: [ collectors ]
      description: >-
        Remove a user from a collector’s list of authorized writers.
      operationId: deleteCollectorWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the collector
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the collector.
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /events:
    x-swagger-router-controller: events
    get:
      security:
        - jwt: []
      summary: Find events
      tags: [ events ]
      operationId: findEvents
      description: >-
        All events are retrieved using this route and using the paramaters as filters you can focus on rooms, bots, or users.
      parameters:
        -
          name: roomId
          description: Get events from specific room
          in: query
          required: false
          type: integer
        -
          name: botId
          description: Get events from specific bot
          in: query
          required: false
          type: string
        -
          name: type
          description: Get events that are a specific type
          in: query
          required: false
          type: string
        -
          name: actionType
          description: Get events that are a specific actionType
          in: query
          required: false
          type: string
        -
          name: sort
          description: >
            Specify the sort order using a field name, e.g. '...?sort=createdAt'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          in: query
          required: false
          type: string
        -
          name: botDataId
          description: Get events from specific botData
          in: query
          required: false
          type: string
        -
          name: botActionId
          description: Get events from specific botAction
          in: query
          required: false
          type: string
        -
          name: userId
          description: Get events from specific user
          in: query
          required: false
          type: string
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when events were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when events were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns all Events
          schema:
            type: array
            items:
              $ref: "#/definitions/EventResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    post:
      security:
        - jwt: []
      summary: Create event
      tags: [ events ]
      description: >-
        Create a new event that can describe any action or information needed to be specifically logged,
        typically used to activity in rooms.
      operationId: postEvents
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Create event properties
            properties:
              log:
                type: string
                description: Human readable log line to describe the context.
              context:
                type: object
                description: Any object, typically JSON, used to describe to some information that needed to be logged.
              actionType:
                type: 'string'
                description: 'This is the type of the event'
              roomId:
                type: integer
                description: Room that this event relates to.
              botId:
                type: string
                description: Bot that this event relates to.
              botDataId:
                type: string
                description: Bot Data that this event relates to.
              botActionId:
                type: string
                description: Bot Action that this event relates to.
              userId:
                type: string
                description: User that this event relates to.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - log
      responses:
        201:
          description: >-
            Created event
          schema:
            $ref: "#/definitions/EventResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /events/bulk:
    x-swagger-router-controller: events
    post:
      security:
        - jwt: []
      summary: Create events in bulk.
      tags: [ events ]
      description: >-
        Create multiple events at once.
      operationId: bulkPostEvent
      parameters:
        -
          name: queryBody
          description: Request body
          in: body
          schema:
            type: array
            items:
              type: object
              description: Create event properties
              properties:
                log:
                  type: string
                  description: Human readable log line to describe the context.
                context:
                  type: object
                  description: Any object, typically JSON, used to describe to some infomration that needed to be logged.
                actionType:
                  type: 'string'
                  description: 'This is the type of the event'
                roomId:
                  type: integer
                  description: Room that this event relates to.
                botId:
                  type: string
                  description: Bot that this event relates to.
                botDataId:
                  type: string
                  description: Bot Data that this event relates to.
                botActionId:
                  type: string
                  description: Bot Action that this event relates to.
                userId:
                  type: string
                  description: User that this event relates to.
                owner:
                  type: string
                  description: >
                    The name of the user to assign as the owner. Defaults to the user that created it
              required:
                - log
      responses:
        200:
          description: >-
            Created
          schema:
            $ref: "#/definitions/BulkCreateResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /events/bulk/{key}/status:
    x-swagger-router-controller: events
    get:
      security:
        - jwt: []
      summary: Get event bulk job status
      tags: [ events ]
      description: >-
        Retrieve the status of the job identified by id in the request.
      operationId: getEventBulkStatus
      parameters:
        -
          name: key
          in: path
          description: >-
            The id the job
          required: true
          type: integer
      responses:
        200:
          description: >-
            Success.
          schema:
            $ref: "#/definitions/GetBulkUpsertStatusResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /events/{key}:
    x-swagger-router-controller: events
    get:
      security:
        - jwt: []
      summary: Get event
      tags: [ events ]
      description: >-
        This route is used to retrieve a single event.
      operationId: getEvent
      parameters:
        -
          name: key
          in: path
          description: >-
            The id the event to retrieve
          required: true
          type: string
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns specified event
          schema:
            $ref: "#/definitions/EventResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generators:
    x-swagger-router-controller: generators
    get:
      security:
        - jwt: []
      summary: Find generators
      tags: [ generators ]
      description: >-
        Get a generator or all generators. You may query using field filters
        with asterisk (*) wildcards. You may also optionally specify sort,
        limit, offset, and a list of fields to include in the response. The
        global default limit will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /generators
        url: http://focus.salesforce.com/docs/api/generators
      operationId: findGenerators
      parameters:
        -
          $ref: "#/parameters/GeneratorFieldsParam"
        -
          name: sort
          in: query
          description: >-
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - isActive
              - aspects
              - subjectQuery
              - createdAt
              - description
              - intervalSecs
              - name
              - updatedAt
              - -isActive
              - -aspects
              - -subjectQuery
              - -createdAt
              - -description
              - -intervalSecs
              - -name
              - -updatedAt
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: description
          in: query
          type: string
          maxLength: 4096
          description: >-
            Filter by the generator description; asterisk (*) wildcards ok.
        -
          name: createdBy
          in: query
          type: string
          description: >-
            Filter by the generator id; asterisk (*) wildcards ok.
        -
          name: isActive
          in: query
          type: boolean
          description: >-
            Filter by whether or not the generator is active.
        -
          name: intervalSecs
          in: query
          type: integer
          description: >-
            Interval (seconds) between each collection.
        -
          name: name
          in: query
          type: string
          description: >-
            Filter by the generator name; asterisk (*) wildcards ok.
        -
          name: subjectQuery
          in: query
          type: string
          minLength: 7
          maxLength: 4096
          description: >-
            Filter by the query to append to GET subjects. Only "absolutePath", "name", "tags" are allowed in subjectQuery.
        -
          name: aspects
          in: query
          description: >-
            Filter by the names of the aspects.
          type: array
          items:
            type: string
        -
          name: tags
          in: query
          items:
            type: string
            maxLength: 60
            pattern: ^[0-9A-Za-z_-]{1,60}$
          description: >-
             Comma-separated list of tags to include/exclude. Tag names are
             case-insensitive. For example, ?tags=FOO,BAR will only return
             aspects with tags FOO and BAR. Prefix each of the tag name with
             a negative sign to indicate that a aspect with that tag should
             be excluded. For example, ?tags=-BAZ,FOO will return only the
             aspects with tag name not equal to BAZ or FOO. A mix of tag
             names with and without minus signs, for example ?tags=BAZ,-FOO
             are not allowed. Generators without tags are not included in the
             include result set.
          type: array
          required: false
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when generators were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when generators were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, returns a list of generators
          schema:
            type: array
            items:
              $ref: "#/definitions/GeneratorResponse"
        400:
          $ref: "#/responses/400"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create generator
      tags: [ generators ]
      description: >-
        Create a new generator and makes the creator the writer of the generator.
      operationId: postGenerator
      parameters:
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: object
            description: A generator configration object.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >-
                  A description of the generator.
              helpEmail:
                type: string
                description: >-
                  The email address where a user can go to get more help about the Generator.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >-
                  The url where a user can go to get more help about the Generator.
              intervalSecs:
                type: integer
                minimum: 1
                default: 60
                description: >-
                  Interval (seconds) between each collection.
              name:
                type: string
                description: A unique and descriptive name for your Generator.
              subjectQuery:
                type: string
                minLength: 7
                maxLength: 4096
                description: The query to append to GET subjects. Only "absolutePath", "name", "tags" are allowed in subjectQuery.
              collectorGroup:
                 description: Name of set of collectors this Sample Generator should try to use.
                 type: string
              aspects:
                description: List of one or more Aspects you want to collect Samples for.
                type: array
                items:
                  type: string
              tags:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case
                  insensitive; allows alpha-numeric characters, underscore (_)
                  and dash (-). Tag names cannot start with a dash (-).
              connection:
                type: object
                description: Information about the connection.
              context:
                type: object
                description: >-
                  Specify the values for any context variables as defined by the Sample Generator Template you are using.
              generatorTemplate:
                type: object
                description: Details of Generator Template.
                properties:
                  name:
                    type: string
                    description: The Generator Template's name.
                  version:
                    type: string
                    description: >-
                      A Generator Template version number (MAJOR.MINOR.PATCH)
                      or a valid x-range, tilde range or caret range. Any of X,
                      x, or * may be used to "stand in" for one of the numeric
                      major, minor or patch values. A tilde range allows
                      patch-level changes if a minor version is specified on
                      the comparator, or allows minor-level changes if not.
                      A caret range allows changes that do not modify the
                      left-most non-zero major, minor or patch number.
                      See https://github.com/npm/node-semver for more details
                      on semver matching.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - aspects
              - generatorTemplate
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/GeneratorResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generators/{key}:
    x-swagger-router-controller: generators
    get:
      security:
        - jwt: []
      summary: Get generator
      tags: [ generators ]
      description: >-
        Retrieve the specified generator.
      operationId: getGenerator
      parameters:
        -
          name: key
          in: path
          description: The id or key of the generator to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/GeneratorFieldsParam"
      responses:
        200:
          description: Success, returns the specified generator.
          schema:
            $ref: "#/definitions/GeneratorResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update generator (partial)
      tags: [ generators ]
      description: >-
        Update the specified generator. Requires user to have write permision. If a field is not included in the query body, that field will not be updated.
      operationId: patchGenerator
      parameters:
        -
          name: key
          in: path
          description: The id or key of the generator to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Request body.
          required: true
          schema:
            type: object
            description: A generator configration object.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >-
                  A description of the generator.
              helpEmail:
                type: string
                description: >-
                  The email address where a user can go to get more help about the generator.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >-
                  The url where a user can go to get more help about the generator.
              intervalSecs:
                type: integer
                minimum: 1
                default: 60
                description: >-
                  Interval (seconds) between each collection.
              name:
                type: string
                readOnly: true
                description: The generator's name.
              subjectQuery:
                type: string
                readOnly: true
                minLength: 7
                maxLength: 4096
                description: The query to append to GET subjects. Only "absolutePath", "name", "tags" are allowed in subjectQuery.
              aspects:
                description: Names of the aspects.
                type: array
                items:
                  type: string
              tags:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case
                  insensitive; allows alpha-numeric characters, underscore (_)
                  and dash (-). Tag names cannot start with a dash (-).
              connection:
                type: object
                description: Information about the connection.
              context:
                type: object
                description: >-
                  Variables accessible inside the transform function.
              collectorGroup:
                 description: Name of set of collectors this Sample Generator should try to use.
                 type: string
              isActive:
                type: boolean
                description: >-
                  Default false. When set to true, the generator will be
                  assigned to a running collector and regularly send in samples.
              generatorTemplate:
                type: object
                description: Details of Generator Template.
                properties:
                  name:
                    type: string
                    description: The Generator Template's name.
                  version:
                    type: string
                    description: >-
                      A Generator Template version number (MAJOR.MINOR.PATCH)
                      or a valid x-range, tilde range or caret range. Any of X,
                      x, or * may be used to "stand in" for one of the numeric
                      major, minor or patch values. A tilde range allows
                      patch-level changes if a minor version is specified on
                      the comparator, or allows minor-level changes if not.
                      A caret range allows changes that do not modify the
                      left-most non-zero major, minor or patch number.
                      See https://github.com/npm/node-semver for more details
                      on semver matching.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: Success, returns the updated generator.
          schema:
            $ref: "#/definitions/GeneratorResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update generator (full)
      tags: [ generators ]
      description: >-
        Update the specified generator. Requires user to have write permision.
        If a field is not included in the query body, that field will be set to null or its default value.

      operationId: putGenerator
      parameters:
        -
          name: key
          in: path
          description: The id or key of the generator to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Request body.
          required: true
          schema:
            type: object
            description: A generator configration object.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >-
                  A description of the generator.
              helpEmail:
                type: string
                description: >-
                  The email address where a user can go to get more help about the generator.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >-
                  The url where a user can go to get more help about the generator.
              intervalSecs:
                type: integer
                minimum: 1
                default: 60
                description: >-
                  Interval (seconds) between each collection.
              name:
                type: string
                readOnly: true
                description: The generator's name.
              subjectQuery:
                type: string
                readOnly: true
                minLength: 7
                maxLength: 4096
                description: The query to append to GET subjects. Only "absolutePath", "name", "tags" are allowed in subjectQuery.
              aspects:
                description: Names of the aspects.
                type: array
                items:
                  type: string
              tags:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case
                  insensitive; allows alpha-numeric characters, underscore (_)
                  and dash (-). Tag names cannot start with a dash (-).
              connection:
                type: object
                description: Information about the connection.
              context:
                type: object
                description: >-
                  Variables accessible inside the transform function.
              collectorGroup:
                 description: Name of set of collectors this Sample Generator should try to use.
                 type: string
              isActive:
                type: boolean
                description: >-
                  Default false. When set to true, the generator will be
                  assigned to a running collector and regularly send in samples.
              generatorTemplate:
                type: object
                description: Details of Generator Template.
                properties:
                  name:
                    type: string
                    description: The Generator Template's name.
                  version:
                    type: string
                    description: >-
                      A Generator Template version number (MAJOR.MINOR.PATCH)
                      or a valid x-range, tilde range or caret range. Any of X,
                      x, or * may be used to "stand in" for one of the numeric
                      major, minor or patch values. A tilde range allows
                      patch-level changes if a minor version is specified on
                      the comparator, or allows minor-level changes if not.
                      A caret range allows changes that do not modify the
                      left-most non-zero major, minor or patch number.
                      See https://github.com/npm/node-semver for more details
                      on semver matching.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - aspects
              - generatorTemplate
      responses:
        200:
          description: Success, returns the updated generator.
          schema:
            $ref: "#/definitions/GeneratorResponse"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generators/{key}/writers:
    x-swagger-router-controller: generators
    get:
      security:
        - jwt: []
      summary: Get generator writers
      tags: [ generators ]
      description: >-
        Get the list of all authorized writers for an generator.
      operationId: getGeneratorWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the generator for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the generator.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the generator
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add generator writer
      tags: [ generators ]
      description: >-
        Add one or more users to an generator’s list of authorized writers.
      operationId: postGeneratorWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the generator for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >-
              User name or id
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/GeneratorWriterResponse"
              description: >-
                The users having write permission to the generator
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generators/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: generators
    get:
      security:
        - jwt: []
      summary: Get generator writer
      tags: [ generators ]
      description: >-
        Determine whether a user is an authorized writer for an generator. Returns the user if authorized, else
        throws 404 if either the writer or generator is not found.

      operationId: getGeneratorWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the generator for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user.
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    delete:
      security:
        - jwt: []
      summary: Delete generator writer
      tags: [ generators ]
      description: >-
        Remove a user from an generator’s list of authorized writers.
      operationId: deleteGeneratorWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the generator
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the generator.
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generatorTemplates:
    x-swagger-router-controller: generatorTemplates
    get:
      security:
        - jwt: []
      summary: Find generatorTemplates
      tags: [ generatorTemplates ]
      description: >-
        Get a generatorTemplate or all generatorTemplates. You may query using
        field filters with asterisk (*) wildcards. You may also optionally
        specify sort, limit, offset, and a list of fields to include in the
        response. The global default limit will apply if no limit param is
        specified.
      externalDocs:
        description: >-
          GET /generatorTemplates
        url: http://focus.salesforce.com/docs/api/generatorTemplates
      operationId: findGeneratorTemplates
      parameters:
        -
          $ref: "#/parameters/GeneratorTemplateFieldsParam"
        -
          name: sort
          in: query
          description: >-
            Specify the sort order using a field name, e.g. '...?sort=name'.
            Prepend the field name with a minus sign to specify descending order,
            e.g. '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - description
              - name
              - version
              - createdAt
              - updatedAt
              - -description
              - -name
              - -version
              - -createdAt
              - -updatedAt
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: name
          in: query
          type: string
          description: >-
            Filter by the generatorTemplate name; asterisk (*) wildcards ok.
        -
          name: version
          in: query
          type: string
          description: >-
            Filter by the generatorTemplate version; asterisk (*) wildcards ok.
        -
          name: tags
          in: query
          items:
            type: string
            maxLength: 60
            pattern: ^[0-9A-Za-z_-]{1,60}$
          description: >-
             Comma-separated list of tags to include/exclude. Tag names are
             case-insensitive. For example, ?tags=FOO,BAR will only return
             aspects with tags FOO and BAR. Prefix each of the tag name with
             a negative sign to indicate that a aspect with that tag should
             be excluded. For example, ?tags=-BAZ,FOO will return only the
             aspects with tag name not equal to BAZ or FOO. A mix of tag
             names with and without minus signs, for example ?tags=BAZ,-FOO
             are not allowed. GeneratorTemplates without tags are not included in the
             include result set.
          type: array
          required: false
        -
          name: isPublished
          in: query
          type: boolean
          description: >-
            Filter by generatorTemplate isPublished (true|false)
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when GeneratorTemplates were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when GeneratorTemplates were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, returns a list of generatorTemplates
          schema:
            type: array
            items:
              $ref: "#/definitions/GeneratorTemplateResponse"
        400:
          $ref: "#/responses/400"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create generatorTemplate
      tags: [ generatorTemplates ]
      description: >-
        Create a new generatorTemplate and makes the creator the writer of the
        generatorTemplate.
      operationId: postGeneratorTemplate
      parameters:
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: object
            description: A generatorTemplate configuration object.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >-
                  A description of the generatorTemplate.
              helpEmail:
                type: string
                description: >-
                  The email address where a user can go to get more help about
                  the generatorTemplate.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >-
                  The url where a user can go to get more help about the
                  generatorTemplate.
              name:
                type: string
                readOnly: true
                description: >-
                  The generatorTemplate's name.
              version:
                type: string
                description: >-
                  The version, in semantic versioning format ( MAJOR.MINOR.PATCH )
              tags:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case
                  insensitive; allows alpha-numeric characters, underscore (_)
                  and dash (-). Tag names cannot start with a dash (-).
              author:
                type: object
                description: >-
                  The author of this generatorTemplate.
              repository:
                type: object
                description: >-
                  The repository where this generatorTemplate is located.
              connection:
                type: object
                description: >-
                  Information about the connection.
              contextDefinition:
                type: object
                description: >-
                  Variables available to connection.url, connection.toUrl, and
                  the transform function.
              transform:
                type: object
                description: >-
                  The body of a javascript function which transforms some data into
                  an array of samples
              isPublished:
                type: boolean
                description: >-
                  Default false. When set to true, the generatorTemplate is
                  available to all users.
                default: false
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - version
              - author
              - connection
              - transform
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/GeneratorTemplateResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generatorTemplates/{key}:
    x-swagger-router-controller: generatorTemplates
    get:
      security:
        - jwt: []
      summary: Get generatorTemplate
      tags: [ generatorTemplates ]
      description: >-
        Retrieve the specified generatorTemplate.
      operationId: getGeneratorTemplate
      parameters:
        -
          name: key
          in: path
          description: The id or key of the generatorTemplate to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/GeneratorTemplateFieldsParam"
      responses:
        200:
          description: Success, returns the specified generatorTemplate.
          schema:
            $ref: "#/definitions/GeneratorTemplateResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update generatorTemplate (partial)
      tags: [ generatorTemplates ]
      description: >-
        Update the specified generatorTemplate. Requires user to have write
        permission. If a field is not included in the query body, that field
        will not be updated.
      operationId: patchGeneratorTemplate
      parameters:
        -
          name: key
          in: path
          description: The id or key of the generatorTemplate to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Request body.
          required: true
          schema:
            type: object
            description: A generatorTemplate configuration object.
            properties:
              isPublished:
                type: boolean
                description: >-
                  Default false. When set to true, the generatorTemplate is
                  available to all users.
                default: false
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: Success, returns the updated generatorTemplate.
          schema:
            $ref: "#/definitions/GeneratorTemplateResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generatorTemplates/{key}/writers:
    x-swagger-router-controller: generatorTemplates
    get:
      security:
        - jwt: []
      summary: Get generatorTemplate writers
      tags: [ generatorTemplates ]
      description: >-
        Get the list of all authorized writers for a generatorTemplate.
      operationId: getGeneratorTemplateWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the generatorTemplate for which the authorized list
            of users are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the
            generatorTemplate.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the generatorTemplate
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add generatorTemplate writer
      tags: [ generatorTemplates ]
      description: >-
        Add one or more users to a generatorTemplate’s list of authorized
        writers.
      operationId: postGeneratorTemplateWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the generatorTemplate for which the authorized list
            of users are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >-
              User name or id
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized
            writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/GeneratorTemplateWriterResponse"
              description: >-
                The users having write permission to the generatorTemplate
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generatorTemplates/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: generatorTemplates
    get:
      security:
        - jwt: []
      summary: Get generatorTemplate writer
      tags: [ generatorTemplates ]
      description: >-
        Determine whether a user is an authorized writer for a generatorTemplate.
        Returns the user if authorized, else throws 404 if either the writer or
        generatorTemplate is not found.
      operationId: getGeneratorTemplateWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the generatorTemplate for which the authorized list
            of users are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns requested user.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the generatorTemplate
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    delete:
      security:
        - jwt: []
      summary: Delete generatorTemplate writer
      tags: [ generatorTemplates ]
      description: >-
        Remove a user from a generatorTemplate’s list of authorized writers.
      operationId: deleteGeneratorTemplateWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the generatorTemplate
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the generatorTemplate.
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /generatorTemplates/{name}/{version}:
    x-swagger-router-controller: generatorTemplates
    get:
      security:
      - jwt: []
      summary: Get generatorTemplate
      tags: [ generatorTemplates ]
      description: >-
        Retrieve the specified generatorTemplate by name and version.
      operationId: getGeneratorTemplateByNameAndVersion
      parameters:
      -
        name: name
        in: path
        description: >-
          The name of the generatorTemplate to be retrieved.
        required: true
        type: string
      -
        name: version
        in: path
        description: >-
          The version of the generatorTemplate to be retrieved.
        required: true
        type: string
      responses:
        200:
          description: >-
            Success, returns a single generatorTemplate
          schema:
            type: object
            items:
              $ref: "#/definitions/GeneratorTemplateResponse"
        400:
          $ref: "#/responses/400"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /globalconfig:
    x-swagger-router-controller: globalconfig
    get:
      security:
        - jwt: []
      summary: Find global config items
      tags: [ globalconfig ]
      description: >-
        Get all global config items. You may optionally specify limit and offset.
        The global default limit will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /globalconfig
        url: http://focus.salesforce.com/docs/api/globalconfig
      operationId: findGlobalConfig
      parameters:
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        - name: createdAt
          in: query
          description: >-
            Filter by time period when globalConfigs were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        - name: updatedAt
          in: query
          description: >-
            Filter by time period when globalConfigs were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, returns a list of global config items.
          schema:
            type: array
            items:
              $ref: "#/definitions/GlobalConfigResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create global config item
      tags: [ globalconfig ]
      description: >-
        Create a new global config item. Requires user to have an admin profile.
      operationId: postGlobalConfig
      parameters:
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: object
            description: A global configration item (key/value pair).
            properties:
              key:
                type: string
                maxLength: 60
              value:
                type: string
            required:
              - key
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/GlobalConfigResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /globalconfig/{key}:
    x-swagger-router-controller: globalconfig
    delete:
      security:
        - jwt: []
      summary: Delete global config item
      tags: [ globalconfig ]
      description: >-
        Delete the specified global config item. Requires user to have an admin profile.
      operationId: deleteGlobalConfig
      parameters:
        -
          name: key
          in: path
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the deleted global config item.
          schema:
            $ref: "#/definitions/GlobalConfigResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get global config item
      tags: [ globalconfig ]
      description: >-
        Retrieve the specified global config item.
      operationId: getGlobalConfig
      parameters:
        -
          name: key
          in: path
          description: The id or key of the global config item to retrieve.
          required: true
          type: string
      responses:
        200:
          description: Success, returns the specified global config item.
          schema:
            $ref: "#/definitions/GlobalConfigResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update global config item
      tags: [ globalconfig ]
      description: >-
        Update the specified global config item. Requires user to have an admin profile. If a field is not included in the query body, that field will not be updated.
      operationId: patchGlobalConfig
      parameters:
        -
          name: key
          in: path
          description: The id or key of the global config item to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Request body.
          required: true
          schema:
            type: object
            description: >-
                  A global config item.
            properties:
              value:
                type: string
      responses:
        200:
          description: Success, returns the updated global config item.
          schema:
            $ref: "#/definitions/GlobalConfigResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /lenses:
    x-swagger-router-controller: lenses
    get:
      security:
        - jwt: []
      summary: Find lenses
      tags: [ lenses ]
      description: >-
        Find a lens or lenses. You may query using field filters with asterisk
        (*) wildcards. You may also optionally specify sort, limit, offset, and
        a list of fields to include in the response. The global default limit
        will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /lenses
        url: http://focus.salesforce.com/docs/api/lenses
      operationId: findLenses
      parameters:
        -
          $ref: "#/parameters/LensesFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - description
              - helpEmail
              - helpUrl
              - id
              - isCustom
              - isPublished
              - name
              - sourceDescription
              - sourceName
              - sourceVersion
              - installedBy
              - createdAt
              - updatedAt
              - lensEventApiVersion
              - -description
              - -helpEmail
              - -helpUrl
              - -id
              - -isCustom
              - -isPublished
              - -name
              - -sourceDescription
              - -sourceName
              - -sourceVersion
              - -installedBy
              - -createdAt
              - -updatedAt
              - -lensEventApiVersion
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: description
          in: query
          required: false
          type: string
          description: >-
            A description of the lens.
        -
          name: helpEmail
          in: query
          required: false
          type: string
          description: >-
            The email address where a user can go to get more help about the
            lens. A lens may choose to display this information to the user e.g.
            if the user clicks a “help” icon attached to the lens.
        -
          name: helpUrl
          in: query
          required: false
          type: string
          description: >-
            The url where a user can go to get more help about the lens. A lens
            may choose to display this information to the user e.g. if the user
            clicks a “help” icon attached to the lens.
        -
          name: lensEventApiVersion
          in: query
          required: false
          type: integer
          default: 1
          description: >-
            The API version for the Lens Event API, e.g. 1, 2, etc.
        -
          name: isCustom
          type: boolean
          in: query
          required: false
          description: >-
            True for any lens which is installed by an administrator (rather
            than pre-installed in Focus).
        -
          name: isPublished
          type: boolean
          in: query
          required: false
          description: >-
            True for any lens which is available to users.
        -
          name: name
          type: string
          in: query
          required: false
          description: The name of the lens.
        -
          name: sourceDescription
          in: query
          required: false
          type: string
          description: >-
            The original lens publisher's description of the lens.
        -
          name: sourceName
          type: string
          in: query
          required: false
          description: The original lens publisher's name of the lens.
        -
          name: sourceVersion
          type: string
          in: query
          required: false
          description: The original lens publisher's version of the lens.
        -
          name: version
          type: string
          in: query
          required: false
          description: The version of the lens.
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when lenses were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when lenses were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, returns a list of lenses.
          schema:
            type: array
            items:
              $ref: "#/definitions/LensesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Install lens
      tags: [ lenses ]
      description: Install a new lens.
      operationId: postLens
      consumes:
        - multipart/form-data
      parameters:
        -
          name: description
          in: formData
          description: >-
            A description of the lens. Leave empty if you want to use the
            description provided by the lens publisher (i.e. sourceDescription).
          type: string
        -
          name: isPublished
          in: formData
          description: >-
            Default false. When set to true, the lens is available to all users.
          type: boolean
          default: false
        -
          name: library
          description: >-
            An archive (zip) of metadata and resources required for a browser to
            render the lens.
          in: formData
          type: file
          format: binary
          required: true
        -
          name: name
          in: formData
          description: >-
            A unique name for the lens. Max 60 characters; case insensitive;
            allows alpha-numeric characters, underscore (_) and dash (-). Leave
            empty if you want to use the name provided by the lens publisher
            (i.e. sourceName).
          type: string
          pattern: ^[0-9A-Za-z_\\-]{0,60}$
        -
          name: version
          in: formData
          description: >-
            A version for the lens. Leave empty if you want to use the
            version provided by the lens publisher (i.e. sourceVersion).
          type: string
        -
          name: owner
          in: formData
          description: >-
            The name of the user to assign as the owner. Defaults to the user that created it
          type: string
      responses:
        201:
          description: Returns created lens
          schema:
            $ref: "#/definitions/LensesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /lenses/{key}:
    x-swagger-router-controller: lenses
    delete:
      security:
        - jwt: []
      summary: Uninstall lens
      tags: [ lenses ]
      description: >-
        Uninstall the specified lens. You will not be allowed to uninstall the
        lens if it is used by any perspectives.
      operationId: deleteLens
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the lens to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the deleted lens.
          schema:
            $ref: "#/definitions/LensesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get lens
      tags: [ lenses ]
      description: >-
        Retrieve the specified lens by its id or name. You may also optionally
        specify a list of fields to include in the response.
      operationId: getLens
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the lens to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/LensesFieldsParam"
      responses:
        200:
          description: >-
            Success, returns the specified lens.
          schema:
            $ref: "#/definitions/LensesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update lens (partial)
      tags: [ lenses ]
      description: >-
        Update selected metadata fields for the specified lens. Note that if you are updating the lens library, you must use PUT (which accepts multipart/form-data).
      operationId: patchLens
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the lens to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          description: Request body
          required: true
          schema:
            type: object
            description: The lens to update.
            properties:
              description:
                description: >-
                  A description of the lens. Leave empty if you want to use the
                  description provided by the lens publisher (i.e. sourceDescription).
                type: string
              isPublished:
                description: >-
                  Default false. When set to true, the lens is available to all users.
                type: boolean
                default: false
              name:
                description: >-
                  A unique name for the lens. Max 60 characters; case insensitive;
                  allows alpha-numeric characters, underscore (_) and dash (-). Leave
                  empty if you want to use the name provided by the lens publisher
                  (i.e. sourceName).
                type: string
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              version:
                description: >-
                  A version for the lens. Leave empty if you want to use the
                  version provided by the lens publisher (i.e. sourceVersion).
                type: string
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Success, returns the updated lens.
          schema:
            $ref: "#/definitions/LensesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update lens (full)
      tags: [ lenses ]
      description: >-
        Install a new version of the specified lens.
      consumes:
        - multipart/form-data
      operationId: putLens
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the lens to update.
          required: true
          type: string
        -
          name: library
          description: >-
            An archive (zip) of metadata and resources required for a browser to
            render the lens.
          in: formData
          type: file
          required: true
        -
          name: description
          in: formData
          description: >-
            A description of the lens. Leave empty if you want to use the
            description provided by the lens publisher (i.e. sourceDescription).
          type: string
        -
          name: isPublished
          in: formData
          description: >-
            Default false. When set to true, the lens is available to all users.
          type: boolean
          default: false
        -
          name: name
          in: formData
          description: >-
            A unique name for the lens. Max 60 characters; case insensitive;
            allows alpha-numeric characters, underscore (_) and dash (-). Leave
            empty if you want to use the name provided by the lens publisher
            (i.e. sourceName).
          type: string
          pattern: ^[0-9A-Za-z_\\-]{0,60}$
        -
          name: version
          in: formData
          description: >-
            A version for the lens. Leave empty if you want to use the
            version provided by the lens publisher (i.e. sourceVersion).
          type: string
        -
          name: owner
          in: formData
          description: >-
            The name of the user to assign as the owner. Defaults to the user that created it
          type: string
      responses:
        200:
          description: >-
            Success, returns the updated lens.
          schema:
            $ref: "#/definitions/LensesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /lenses/{key}/writers:
    x-swagger-router-controller: lenses
    delete:
      security:
        - jwt: []
      summary: Delete lens writers
      tags: [ lenses ]
      description: >-
        Remove all users from a lens' list of authorized writers.
      operationId: deleteLensWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the lens.
          required: true
          type: string
      responses:
        204:
          description: >-
            The lens is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get lens writers
      tags: [ lenses ]
      description: >-
        Get the list of all authorized writers for a lens.
      operationId: getLensWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the lens for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns The users having write permission to the lens.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the lens
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add lens writer
      tags: [ lenses ]
      description: >-
        Add one or more users to a lens' list of authorized writers.
      operationId: postLensWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the lens for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/LensWriterResponse"
              description: >-
                The users having write permission to the lens
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /lenses/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: lenses
    delete:
      security:
        - jwt: []
      summary: Delete lens writer
      tags: [ lenses ]
      description: >-
        Remove a user from a lens’ list of authorized writers.
      operationId: deleteLensWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the lens
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the lens.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get lens writer
      tags: [ lenses ]
      description: >-
        Determine whether a user is an authorized writer for lens.
      operationId: getLensWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the aspect for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /logout:
    x-swagger-router-controller: logout
    get:
      security:
        - jwt: []
      summary: Logout
      tags: [ logout ]
      description: >-
        Logout authenticated user.
      operationId: logoutUser
      responses:
        200:
          description: >-
            User logged out.
          schema:
            type: object
            description: Logout message
            properties:
              Success:
                type: boolean
                readOnly: true
              message:
                type: string
                readOnly: true
                maxLength: 2082
                description: >
                  Logout message.
        401:
          description: >-
            Authentication Error
          schema:
            type: object
            description: Logout message
            properties:
              Success:
                type: boolean
                readOnly: true
              message:
                type: string
                readOnly: true
                maxLength: 2082
                description: >
                  Logout message.
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /perspectives:
    x-swagger-router-controller: perspectives
    get:
      security:
        - jwt: []
      summary: Find perspectives
      tags: [ perspectives ]
      description: >-
        Find a perspective or perspectives. You may query using field filters
        with asterisk (*) wildcards. You may also optionally specify sort,
        limit, offset, and a list of fields to include in the response. The
        global default limit will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /perspectives
        url: http://focus.salesforce.com/docs/api/perspectives
      operationId: findPerspectives
      parameters:
        -
          $ref: "#/parameters/PerspectivesFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. "...?sort=name". Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - id
              - name
              - rootSubject
              - aspectFilter
              - aspectTagFilter
              - subjectTagFilter
              - statusFilter
              - lensId
              - createdBy
              - createdAt
              - updatedAt
              - -id
              - -name
              - -rootSubject
              - -aspectTagFilter
              - -subjectTagFilter
              - -statusFilter
              - -lensId
              - -createdBy
              - -createdAt
              - -updatedAt
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: name
          in: query
          description: >-
            Filter by name; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: rootSubject
          in: query
          description: >-
            Filter by root subject; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when perspectives were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when perspectives were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, returns a list of perspectives.
          schema:
            type: array
            items:
              $ref: "#/definitions/PerspectivesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create perspective
      tags: [ perspectives ]
      description: >-
        Create a new perspective.
      operationId: postPerspective
      parameters:
        -
          name: queryBody
          description: Request body
          in: body
          schema:
            type: object
            description: >
              A named combination of a set of subjects and their samples rendered by a
              particular lens.
            properties:
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  The name of the perspective
              rootSubject:
                type: string
                maxLength: 4096
                description: >
                  The absolute path of the root subject.
              aspectFilter:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of aspect names to filter; Aspect name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              aspectTagFilter:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of aspect tag names to filter; Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              subjectTagFilter:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of subject tag names to filter; Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              aspectFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              aspectTagFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              subjectTagFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              statusFilter:
                type: array
                items:
                  type: string
                  enum:
                    - Critical
                    - Invalid
                    - Timeout
                    - Warning
                    - Info
                    - OK
                    - "-Critical"
                    - "-Invalid"
                    - "-Timeout"
                    - "-Warning"
                    - "-Info"
                    - "-OK"
                description: >
                  Array of sample status to filter; Status values can only be one of these:
                  Critical, Invalid, Timeout, Warning, Info, OK, -Critical, -Invalid, -Timeout, -Warning, -Info, -OK.
              lensId:
                type: string
                description: >
                  The id of Lens.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - lensId
              - rootSubject
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/PerspectivesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /perspectives/{key}:
    x-swagger-router-controller: perspectives
    delete:
      security:
        - jwt: []
      summary: Delete perspective
      tags: [ perspectives ]
      description: >-
        Delete the specified perspective.
      operationId: deletePerspective
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the perspective to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the deleted perspective.
          schema:
            $ref: "#/definitions/PerspectivesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get perspective
      tags: [ perspectives ]
      description: >-
        Retrieve the specified perspective by its id or name. You may also
        optionally specify a list of fields to include in the response.
      operationId: getPerspective
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the perspective to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/PerspectivesFieldsParam"
      responses:
        200:
          description: >-
            Success, returns the specified perspective.
          schema:
            $ref: "#/definitions/PerspectivesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update perspective (partial)
      tags: [ perspectives ]
      description: >-
        Update the specified perspective. If a field is not included in the
        query body, that field will not be updated.
      operationId: patchPerspective
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the perspective to update.
          required: true
          type: string
        -
          name: queryBody
          description: Request body
          in: body
          required: true
          schema:
            type: object
            description: >
              A named combination of a set of subjects and their samples rendered by a particular lens.
            properties:
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  The name of the perspective
              rootSubject:
                type: string
                maxLength: 4096
                description: >
                  The absolute path of the root subject.
              aspectFilter:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of aspect names to filter; Aspect name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              aspectTagFilter:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of aspect tag names to filter; Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              subjectTagFilter:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of subject tag names to filter; Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              aspectFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              aspectTagFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              subjectTagFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              statusFilter:
                type: array
                default: []
                items:
                  type: string
                  enum:
                    - Critical
                    - Invalid
                    - Timeout
                    - Warning
                    - Info
                    - OK
                    - "-Critical"
                    - "-Invalid"
                    - "-Timeout"
                    - "-Warning"
                    - "-Info"
                    - "-OK"
                description: >
                  Array of sample status to filter; Status values can only be one of these:
                  Critical, Invalid, Timeout, Warning, Info, OK, -Critical, -Invalid, -Timeout, -Warning, -Info, -OK.
              lensId:
                type: string
                description: >
                  The id of Lens.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Success, returns the updated perspective.
          schema:
            $ref: "#/definitions/PerspectivesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update perspective (full)
      tags: [ perspectives ]
      description: >-
        Update the specified perspective. If a field is not included in the
        query body, that field will be set to null or its default value.
      operationId: putPerspective
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the perspective to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              A named combination of a set of subjects and their samples rendered by a
              particular lens.
            properties:
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  The name of the perspective.
              rootSubject:
                type: string
                maxLength: 4096
                description: >
                  The absolute path of the root subject.
              aspectFilter:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of aspect names to filter; Aspect name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              aspectTagFilter:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of aspect tag names to filter; Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              subjectTagFilter:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_\\-]{1,60}$
                description: >
                  Array of subject tag names to filter; Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              statusFilter:
                type: array
                default: []
                items:
                  type: string
                  enum:
                    - Critical
                    - Invalid
                    - Timeout
                    - Warning
                    - Info
                    - OK
                    - "-Critical"
                    - "-Invalid"
                    - "-Timeout"
                    - "-Warning"
                    - "-Info"
                    - "-OK"
                description: >
                  Array of sample status to filter; Status values can only be one of these:
                  Critical, Invalid, Timeout, Warning, Info, OK, -Critical, -Invalid, -Timeout, -Warning, -Info, -OK.
              lensId:
                type: string
                description: >
                  The id of Lens.
              aspectFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              aspectTagFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              subjectTagFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              statusFilterType:
                type: string
                enum:
                  - INCLUDE
                  - EXCLUDE
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - lensId
              - rootSubject
      responses:
        200:
          description: >-
            Success, returns the updated perspective
          schema:
            $ref: "#/definitions/PerspectivesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /perspectives/{key}/writers:
    x-swagger-router-controller: perspectives
    delete:
      security:
        - jwt: []
      summary: Delete perspective writers
      tags: [ perspectives ]
      description: >-
        Remove all users from a perspective’s list of authorized writers.
      operationId: deletePerspectiveWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the perspective.
          required: true
          type: string
      responses:
        204:
          description: >-
            The perspective is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get perspective writers
      tags: [ perspectives ]
      description: >-
        Get the list of all authorized writers for a perspective.
      operationId: getPerspectiveWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the perspective for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns The users having write permission to the perspective.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the perspective
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add perspective writer
      tags: [ perspectives ]
      description: >-
        Add one or more users to a perspective's list of authorized writers.
      operationId: postPerspectiveWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the perspective for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/PerspectiveWriterResponse"
              description: >-
                The users having write permission to the perspective
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
            $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /perspectives/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: perspectives
    delete:
      security:
        - jwt: []
      summary: Delete perspective writer
      tags: [ perspectives ]
      description: >-
        Remove a user from a perspective's list of authorized writers.
      operationId: deletePerspectiveWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the perspective
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the perspective.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get perspective writer
      tags: [ perspectives ]
      description: >-
        Determine whether a user is an authorized writer for perspective.
      operationId: getPerspectiveWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the perspective for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /profiles:
    x-swagger-router-controller: profiles
    get:
      security:
        - jwt: []
      summary: Find profiles
      tags: [ profiles ]
      description: >-
        Find a profile or profiles. You may query using field filters with
        asterisk (*) wildcards. You may also optionally specify sort, limit,
        offset, and a list of fields to include in the response. The global
        default limit will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /profiles
        url: http://focus.salesforce.com/docs/api/profiles
      operationId: findProfiles
      parameters:
        -
          $ref: "#/parameters/ProfilesFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - id
              - name
              - aspectAccess
              - botAccess
              - eventAccess
              - lensAccess
              - perspectiveAccess
              - profileAccess
              - roomAccess
              - roomTypeAccess
              - sampleAccess
              - subjectAccess
              - userAccess
              - createdBy
              - createdAt
              - updatedAt
              - -id
              - -name
              - -aspectAccess
              - -botAccess
              - -eventAccess
              - -lensAccess
              - -perspectiveAccess
              - -profileAccess
              - -roomAccess
              - -roomTypeAccess
              - -sampleAccess
              - -subjectAccess
              - -userAccess
              - -createdBy
              - -createdAt
              - -updatedAt
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        - name: createdAt
          in: query
          description: >-
            Filter by time period when profiles were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        - name: updatedAt
          in: query
          description: >-
            Filter by time period when profiles were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, returns a list of profiles.
          schema:
            type: array
            items:
              $ref: "#/definitions/ProfilesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create profile
      tags: [ profiles ]
      description: >-
        Create a new profile.
      operationId: postProfile
      parameters:
        -
          name: queryBody
          in: body
          schema:
            type: object
            description: >
              A named set of read/write privileges.
            properties:
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  The name of the profile.
              aspectAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write aspects.
              botAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write bots.
              eventAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write events.
              lensAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write lenses.
              perspectiveAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write perspectives.
              profileAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write profiles.
              roomAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: rw
                description: >
                  The permission to read and/or write rooms.
              roomTypeAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write roomTypes.
              sampleAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write samples.
              subjectAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write subjects.
              userAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write users.
            required:
              - name
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/ProfilesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /profiles/{key}:
    x-swagger-router-controller: profiles
    delete:
      security:
        - jwt: []
      summary: Delete profile
      tags: [ profiles ]
      description: >-
        Delete the specified profile. You will not be allowed to delete the
        profile if there are any users assigned to it.
      operationId: deleteProfile
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the profile to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the deleted profile.
          schema:
            $ref: "#/definitions/ProfilesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get profile
      tags: [ profiles ]
      description: >-
        Retrieve the specified profile by its id or name. You may also
        optionally specify a list of fields to include in the response.
      operationId: getProfile
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the profile to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/ProfilesFieldsParam"
      responses:
        200:
          description: >-
            Success, returns the specified profile.
          schema:
            $ref: "#/definitions/ProfilesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update profile (partial)
      tags: [ profiles ]
      description: >-
        Update the specified profile. If a field is not included in the query
        body, that field will not be updated.
      operationId: patchProfile
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the profile to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              A named set of read/write privileges.
            properties:
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  The name of the profile.
              aspectAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write aspects.
              botAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write bots.
              eventAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write events.
              lensAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write lenses.
              perspectiveAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write perspectives.
              profileAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write profiles.
              roomAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: rw
                description: >
                  The permission to read and/or write rooms.
              roomTypeAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write roomTypes.
              sampleAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write samples.
              subjectAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write subjects.
              userAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write users.
      responses:
        200:
          description: >-
            Success, returns the updated profile.
          schema:
            $ref: "#/definitions/ProfilesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update profile (full)
      tags: [ profiles ]
      description: >-
        Update the specified profile. If a field is not included in the query
        body, that field will be set to null or its default value.
      operationId: putProfile
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the profile to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              A named set of read/write privileges.
            properties:
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  The name of the profile.
              aspectAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write aspects.
              botAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write bots.
              eventAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write events.
              lensAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write lenses.
              perspectiveAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write perspectives.
              profileAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write profiles.
              roomAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: rw
                description: >
                  The permission to read and/or write rooms.
              roomTypeAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write roomTypes.
              sampleAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write samples.
              subjectAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write subjects.
              userAccess:
                type: string
                maxLength: 2
                enum:
                  - r
                  - rw
                default: r
                description: >
                  The permission to read and/or write users.
            required:
              - name
      responses:
        200:
          description: >-
            Success, returns the updated profile.
          schema:
            $ref: "#/definitions/ProfilesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /register:
    x-swagger-router-controller: register
    post:
      summary: Register user
      tags: [ register ]
      description: >-
        Register a user with email and password.
      operationId: registerUser
      parameters:
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: object
            description: >
              A user who interacts with the Refocus system.
            properties:
              email:
                type: string
                maxLength: 254
                description: >
                  The user's email address.
              password:
                type: string
                format: password
                description: >
                  The user's password.
              username:
                type: string
                maxLength: 254
                description: >
                  User name provided by the user
            required:
              - email
              - password
              - username

      responses:
        201:
          description: >-
            User created.
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /rooms:
    x-swagger-router-controller: rooms
    get:
      security:
        - jwt: []
      tags: [ rooms ]
      operationId: findRooms
      parameters:
        -
          name: name
          description: Filter rooms by name
          in: query
          required: false
          type: string
        -
          name: active
          description: Filter rooms by active flag
          in: query
          required: false
          type: boolean
        -
          name: type
          description: Filter room by roomType
          in: query
          required: false
          type: string
        -
          name: origin
          description: Filter rooms by origin
          in: query
          pattern: ^[0-9A-Za-z_\\-]{0,60}$
          required: false
          type: string
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when rooms were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when rooms were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: sort
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          in: query
          required: false
          type: string
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns all rooms
          schema:
            type: array
            items:
              $ref: "#/definitions/RoomResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    post:
      security:
        - jwt: []
      summary: Create room
      tags: [ rooms ]
      description: Create a new room with a name
      operationId: postRooms
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Create room properties
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the room
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              active:
                type: boolean
                description: If the room is active
              type:
                type: string
                maxLength: 254
                description: RoomType of the room
              origin:
                type: string
                maxLength: 60
                default: other
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
                description: Tracks where refocus room was created from
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
              - type
      responses:
        201:
          description: >-
            Created room
          schema:
            $ref: "#/definitions/RoomResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /rooms/{key}:
    x-swagger-router-controller: rooms
    delete:
      security:
        - jwt: []
      summary: Delete room
      tags: [ rooms ]
      description: >-
        Delete a specific room
      operationId: deleteRoom
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the room to retrieve
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, Deleted RoomType
          schema:
            $ref: "#/definitions/RoomResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    get:
      security:
        - jwt: []
      summary: Get room
      tags: [ rooms ]
      operationId: getRoom
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the room to retrieve
          required: true
          type: string
        -
          name: active
          description: Get rooms depending on its active tag
          in: query
          required: false
          type: boolean
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns specified room
          schema:
            $ref: "#/definitions/RoomResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    patch:
      security:
        - jwt: []
      summary: Update room (partial)
      tags: [ rooms ]
      description: Update room fields
      operationId: patchRoom
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the room to retrieve
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Update specified room fields
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the room
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              active:
                type: boolean
                description: If the room is active
              type:
                type: string
                maxLength: 254
                description: Id of roomType
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Updated field
          schema:
            $ref: "#/definitions/RoomResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /rooms/{key}/writers:
    x-swagger-router-controller: rooms
    delete:
      security:
        - jwt: []
      summary: Delete room writers
      tags: [ rooms ]
      description: >-
        Remove all users from a room's list of authorized writers.
      operationId: deleteRoomWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the room.
          required: true
          type: string
      responses:
        204:
          description: >-
            The room is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get room writers
      tags: [ rooms ]
      description: >-
        Get the list of all authorized writers for a room.
      operationId: getRoomWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the room for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the room.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the room
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add room writer
      tags: [ rooms ]
      description: >-
        Add one or more users to a room's list of authorized writers.
      operationId: postRoomWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the room for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/RoomWriterResponse"
              description: >-
                The users having write permission to the room
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /rooms/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: rooms
    delete:
      security:
        - jwt: []
      summary: Delete rooms writer
      tags: [ rooms ]
      description: >-
        Remove a user from a room's list of authorized writers.
      operationId: deleteRoomWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the rooms
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the room.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get room writer
      tags: [ rooms ]
      description: >-
        Determine whether a user is an authorized writer for room.
      operationId: getRoomWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the room for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /rooms/{roomId}/data:
    x-swagger-router-controller: botData
    get:
      security:
        - jwt: []
      summary: Get room bot data
      tags: [ rooms ]
      operationId: findBotData
      parameters:
        -
          name: roomId
          in: path
          description: >-
            The id of the room to retrieve bot data from
          required: true
          type: integer
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns specified bot data
          schema:
            type: array
            items:
              $ref: "#/definitions/BotDataResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /rooms/{roomId}/bots/{botId}/data:
    x-swagger-router-controller: botData
    get:
      security:
        - jwt: []
      summary: Get room bot data
      tags: [ rooms ]
      operationId: findBotData
      parameters:
        -
          name: roomId
          in: path
          description: >-
            The id of the room to retrieve bot data from
          required: true
          type: integer
        -
          name: botId
          in: path
          description: >-
            The id of the bot which people want to reference
          required: true
          type: string
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns specified bot data
          schema:
            type: array
            items:
              $ref: "#/definitions/BotDataResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /roomTypes:
    x-swagger-router-controller: roomTypes
    get:
      security:
        - jwt: []
      tags: [ roomTypes ]
      operationId: findRoomTypes
      parameters:
        -
          name: name
          description: Filter roomTypes by name
          in: query
          required: false
          type: string
        -
          name: isEnabled
          description: Filter roomTypes by active flag
          in: query
          required: false
          type: boolean
        -
          name: type
          description: Filter roomType by roomTypeType
          in: query
          required: false
          type: string
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when roomTypes were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when roomTypes were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns all roomTypes
          schema:
            type: array
            items:
              $ref: "#/definitions/RoomTypeResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    post:
      security:
        - jwt: []
      summary: Create roomType
      tags: [ roomTypes ]
      description: Create a new roomType with a name
      operationId: postRoomTypes
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Create roomType properties
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the roomType
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              isEnabled:
                type: boolean
                description: If the roomType is active
              settings:
                type: object
                description: Default settings for roomType
              rules:
                type: array
                description: Default rules for roomType
                items:
                  type: object
              bots:
                type: array
                description: Default bots for roomType
                items:
                  type: string
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
      responses:
        201:
          description: >-
            Created roomType
          schema:
            $ref: "#/definitions/RoomTypeResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /roomTypes/{key}:
    x-swagger-router-controller: roomTypes
    delete:
      security:
        - jwt: []
      summary: Delete roomType
      tags: [ roomTypes ]
      description: >-
        Delete a specific roomType
      operationId: deleteRoomType
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the roomType to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, Deleted RoomType
          schema:
            $ref: "#/definitions/RoomTypeResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    get:
      security:
        - jwt: []
      summary: Get roomType
      tags: [ roomTypes ]
      operationId: getRoomType
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the roomType to retrieve
          required: true
          type: string
        -
          name: active
          description: Get roomTypes depending on its active tag
          in: query
          required: false
          type: boolean
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
      responses:
        200:
          description: >-
            Success, returns specified roomType
          schema:
            $ref: "#/definitions/RoomTypeResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

    patch:
      security:
        - jwt: []
      summary: Update roomType (partial)
      tags: [ roomTypes ]
      description: Update roomType fields
      operationId: patchRoomType
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the roomType to retrieve
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: Update specified roomType fields
            properties:
              name:
                type: string
                maxLength: 254
                description: Name of the roomType
                pattern: ^[0-9A-Za-z_\\-]{0,60}$
              isEnabled:
                type: boolean
                description: If the roomType is active
              settings:
                type: object
                description: Default settings for roomType
              rules:
                type: array
                description: Default rules for roomType
                items:
                  type: object
              bots:
                type: array
                description: Default bots for roomType
                items:
                  type: string
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Updated field
          schema:
            $ref: "#/definitions/RoomTypeResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /roomTypes/{key}/writers:
    x-swagger-router-controller: roomTypes
    delete:
      security:
        - jwt: []
      summary: Delete roomType writers
      tags: [ roomTypes ]
      description: >-
        Remove all users from a roomType's list of authorized writers.
      operationId: deleteRoomTypeWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the RoomType.
          required: true
          type: string
      responses:
        204:
          description: >-
            The RoomType is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get RoomType writers
      tags: [ roomTypes ]
      description: >-
        Get the list of all authorized writers for a RoomType.
      operationId: getRoomTypeWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the RoomType for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the RoomType.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the RoomType
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add RoomType writer
      tags: [ roomTypes ]
      description: >-
        Add one or more users to a RoomType's list of authorized writers.
      operationId: postRoomTypeWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the RoomType for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/RoomTypeWriterResponse"
              description: >-
                The users having write permission to the room
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /roomTypes/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: roomTypes
    delete:
      security:
        - jwt: []
      summary: Delete RoomTypes writer
      tags: [ roomTypes ]
      description: >-
        Remove a user from a RoomType's list of authorized writers.
      operationId: deleteRoomTypeWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the RoomType
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the RoomType.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get RoomType writer
      tags: [ roomTypes ]
      description: >-
        Determine whether a user is an authorized writer for RoomType.
      operationId: getRoomTypeWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the RoomType for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /samples:
    x-swagger-router-controller: samples
    get:
      security:
        - jwt: []
      summary: Find samples
      tags: [ samples ]
      description: >-
        Find a sample or samples. You may query using field filters with
        asterisk (*) wildcards. You may also optionally specify sort, limit,
        offset, and a list of fields to include in the response. The global
        default limit will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /samples
        url: http://focus.salesforce.com/docs/api/samples
      operationId: findSamples
      parameters:
        -
          $ref: "#/parameters/SamplesFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - name
              - messageBody
              - messageCode
              - status
              - value
              - createdAt
              - updatedAt
              - -messageBody
              - -messageCode
              - -status
              - -value
              - -createdAt
              - -updatedAt
              - -name
              # TODO aspect name
              # TODO subject absolutePath
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: name
          in: query
          description: >-
            Filter by sample name; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: messageCode
          in: query
          description: >-
            Filter by sample messageCode; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: status
          in: query
          description: >-
            Filter by sample status (Critical|Invalid|Timeout|Warning|Info|OK).
          required: false
          type: string
        -
          name: previousStatus
          in: query
          description: >-
            Filter by sample previousStatus (Critical|Invalid|Timeout|Warning|Info|OK).
          required: false
          type: string
        -
          name: value
          in: query
          description: >-
            Filter by sample value (BOOLEAN|NUMERIC|PERCENT).
          required: false
          type: string
      responses:
        200:
          description: >-
            Success, returns a list of samples.
          schema:
            type: array
            items:
              $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create sample
      tags: [ samples ]
      description: >-
        Create a new sample.
      operationId: postSample
      parameters:
        -
          name: queryBody
          description: Request body
          in: body
          schema:
            type: object
            description: >
              An observation of a particular aspect for a particular subject at a
              particular point in time.
            properties:
              messageBody:
                type: string
                description: >
                  Optional message about the sample value. Informational only--not used to
                  determine the status of the sample. It's up to the lens whether/how to
                  display this, will typically be displayed only on hover or click.
                maxLength: 4096
              messageCode:
                type: string
                maxLength: 5
                description: >
                  Optional 5-charater code about the sample value. Informational only--not
                  used to determine the status of the sample. It's up to the lens
                  whether/how to display this, will typically be displayed without having
                  to hover or click.
              value:
                type: string
                maxLength: 255
                description: >
                  Stored as a string but will be treated as whatever the aspect’s
                  valueType was specified as, i.e. [BOOLEAN|NUMERIC|PERCENT]. If timeout
                  occurs, value is set to null.
              relatedLinks:
                type: array
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              aspectId:
                type: string
                description: >
                  TODO
              subjectId:
                type: string
                description: >
                  TODO
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - aspectId
              - subjectId
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /samples/{key}:
    x-swagger-router-controller: samples
    delete:
      security:
        - jwt: []
      summary: Delete sample
      tags: [ samples ]
      description: >-
        Delete the specified sample.
      operationId: deleteSample
      parameters:
        -
          name: key
          in: path
          description: >-
            The name of the sample to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success
          schema:
            $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get sample
      tags: [ samples ]
      description: >-
        Retrieve the specified sample by its name. You may also optionally
        specify a list of fields to include in the response.
      operationId: getSample
      parameters:
        -
          name: key
          in: path
          description: >-
            The name of the sample to retrieve
          required: true
          type: string
        -
          $ref: "#/parameters/SamplesFieldsParam"
      responses:
        200:
          description: >-
            Success.
          schema:
            $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update sample (partial)
      tags: [ samples ]
      description: >-
        Update the specified sample. If a field is not included in the query
        body, that field will not be updated.
      operationId: patchSample
      parameters:
        -
          name: key
          in: path
          description: >-
            The name of the sample to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              An observation of a particular aspect for a particular subject at a
              particular point in time.
            properties:
              messageBody:
                type: string
                description: >
                  Optional message about the sample value. Informational only--not used to
                  determine the status of the sample. It's up to the lens whether/how to
                  display this, will typically be displayed only on hover or click.
                maxLength: 4096
              messageCode:
                type: string
                maxLength: 5
                description: >
                  Optional 5-charater code about the sample value. Informational only--not
                  used to determine the status of the sample. It's up to the lens
                  whether/how to display this, will typically be displayed without having
                  to hover or click.
              value:
                type: string
                maxLength: 255
                description: >
                  Stored as a string but will be treated as whatever the aspect’s
                  valueType was specified as, i.e. [BOOLEAN|NUMERIC|PERCENT]. If timeout
                  occurs, value is set to null.
              relatedLinks:
                type: array
                default: []
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Success.
          schema:
            $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update sample (full)
      tags: [ samples ]
      description: >-
        Update the specified sample. If a field is not included in the query
        body, that field will be set to null or its default value.
      operationId: putSample
      parameters:
        -
          name: key
          in: path
          description: >-
            The name of the sample to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              An observation of a particular aspect for a particular subject at a
              particular point in time.
            properties:
              messageBody:
                type: string
                description: >
                  Optional message about the sample value. Informational only--not used to
                  determine the status of the sample. It's up to the lens whether/how to
                  display this, will typically be displayed only on hover or click.
                maxLength: 4096
              messageCode:
                type: string
                maxLength: 5
                description: >
                  Optional 5-charater code about the sample value. Informational only--not
                  used to determine the status of the sample. It's up to the lens
                  whether/how to display this, will typically be displayed without having
                  to hover or click.
              value:
                type: string
                maxLength: 255
                description: >
                  Stored as a string but will be treated as whatever the aspect’s
                  valueType was specified as, i.e. [BOOLEAN|NUMERIC|PERCENT]. If timeout
                  occurs, value is set to null.
              relatedLinks:
                type: array
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: >-
            Success.
          schema:
            $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /samples/upsert:
    x-swagger-router-controller: samples
    post:
      security:
        - jwt: []
      summary: Create or update sample
      tags: [ samples ]
      description: >-
        Create or update a sample by name.
      operationId: upsertSample
      parameters:
        -
          name: queryBody
          description: Request body
          in: body
          schema:
            type: object
            description: >
              An observation of a particular aspect for a particular subject at a
              particular point in time.
            properties:
              messageBody:
                type: string
                description: >
                  Optional message about the sample value. Informational only--not used to
                  determine the status of the sample. It's up to the lens whether/how to
                  display this, will typically be displayed only on hover or click.
                maxLength: 4096
              messageCode:
                type: string
                maxLength: 5
                description: >
                  Optional 5-charater code about the sample value. Informational only--not
                  used to determine the status of the sample. It's up to the lens
                  whether/how to display this, will typically be displayed without having
                  to hover or click.
              name:
                type: string
                description: >
                  TODO
              value:
                type: string
                maxLength: 255
                description: >
                  Stored as a string but will be treated as whatever the aspect’s
                  valueType was specified as, i.e. [BOOLEAN|NUMERIC|PERCENT]. If timeout
                  occurs, value is set to null.
              relatedLinks:
                type: array
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
      responses:
        200:
          description: >-
            Success, returns created or updated sample.
          schema:
            $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /samples/upsert/bulk:
    x-swagger-router-controller: samples
    post:
      security:
        - jwt: []
      summary: Create or update samples
      tags: [ samples ]
      description: >-
        Create or update multiple samples.
      operationId: bulkUpsertSample
      produces:
        - text/plain; charset=utf-8
      parameters:
        -
          name: queryBody
          description: Request body
          in: body
          schema:
            type: array
            items:
              type: object
              description: >
                An observation of a particular aspect for a particular subject at a
                particular point in time.
              properties:
                messageBody:
                  type: string
                  description: >
                    Optional message about the sample value. Informational only--not used to
                    determine the status of the sample. It's up to the lens whether/how to
                    display this, will typically be displayed only on hover or click.
                  maxLength: 4096
                messageCode:
                  type: string
                  maxLength: 5
                  description: >
                    Optional 5-charater code about the sample value. Informational only--not
                    used to determine the status of the sample. It's up to the lens
                    whether/how to display this, will typically be displayed without having
                    to hover or click.
                name:
                  type: string
                  description: >
                    TODO
                value:
                  type: string
                  maxLength: 255
                  description: >
                    Stored as a string but will be treated as whatever the aspect’s
                    valueType was specified as, i.e. [BOOLEAN|NUMERIC|PERCENT]. If timeout
                    occurs, value is set to null.
                owner:
                  type: string
                  description: >
                    The name of the user to assign as the owner. Defaults to the user that created it
              required:
              - name
      responses:
        200:
          description: >-
            Success, returns OK
          schema:
            $ref: "#/definitions/BulkUpsertResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /samples/upsert/bulk/{key}/status:
    x-swagger-router-controller: samples
    get:
      security:
        - jwt: []
      summary: Get sample upsert job status
      tags: [ samples ]
      description: >-
        Retrieve the status of the job identified by id in the request.
      operationId: getSampleBulkUpsertStatus
      parameters:
        -
          name: key
          in: path
          description: >-
            The id the job
          required: true
          type: integer
      responses:
        200:
          description: >-
            Success.
          schema:
            $ref: "#/definitions/GetBulkUpsertStatusResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /samples/{key}/relatedLinks:
    x-swagger-router-controller: samples
    delete:
      security:
        - jwt: []
      summary: Delete sample related links
      tags: [ samples ]
      description: >-
        Delete all the related links of the specified sample.
      operationId: deleteSampleRelatedLinks
      parameters:
        -
          name: key
          in: path
          description: >-
            The name of the sample for which related links needs to be
            deleted.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the updated sample.
          schema:
            $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /samples/{key}/relatedLinks/{relName}:
    x-swagger-router-controller: samples
    delete:
      security:
        - jwt: []
      summary: Delete sample related link
      tags: [ samples ]
      description: >-
        Delete the specified related link of the specified sample.
      operationId: deleteSampleRelatedLinks
      parameters:
        -
          name: key
          in: path
          description: >-
            The name of the sample for which related link needs to be
            deleted.
          required: true
          type: string
        -
          name: relName
          in: path
          description: >-
            The name of the related link to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the updated sample.
          schema:
            $ref: "#/definitions/SamplesResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /ssoconfig:
    x-swagger-router-controller: ssoconfig
    get:
      security:
        - jwt: []
      summary: Get SSO config
      tags: [ ssoconfig ]
      description: >-
        Retrieves SSO Config.
      operationId: getSSOConfig
      responses:
        200:
          description: >-
            Success, returns SSO config
          schema:
            $ref: "#/definitions/SSOConfigResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create SSO config
      tags: [ ssoconfig ]
      description: >-
        Create SSO config. POST will throw SSOConfigCreateConstraintError if
        SSOConfig already exists.
      operationId: postSSOConfig
      parameters:
        -
          name: queryBody
          in: body
          schema:
            type: object
            description: >
              Configuration parameters to enable SSO in Refocus.
            properties:
              samlEntryPoint:
                type: string
                maxLength: 2082
                description: >
                  Identity Provider endpoint.
              samlIssuer:
                type: string
                maxLength: 2082
                description: >
                  Issuer string to supply to Identity Provider.
            required:
              - samlEntryPoint
              - samlIssuer
      responses:
        201:
          description: >-
            Returns created SSO Config
          schema:
            $ref: "#/definitions/SSOConfigResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"
    delete:
      security:
        - jwt: []
      summary: Delete SSO config
      tags: [ ssoconfig ]
      description: >-
        Delete SSO Config.
      operationId: deleteSSOConfig
      responses:
        200:
          description: >-
            Returns deleted SSO config
          schema:
            $ref: "#/definitions/SSOConfigResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update SSO config (partial)
      tags: [ ssoconfig ]
      description: >-
        Update the specified SSO Config. If a field is not included in the query
        body, that field will not be updated.
      operationId: patchSSOConfig
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              Configuration parameters to enable SSO in Refocus.
            properties:
              samlEntryPoint:
                type: string
                maxLength: 2082
                description: >
                  Identity Provider endpoint.
              samlIssuer:
                type: string
                maxLength: 2082
                description: >
                  Issuer string to supply to Identity Provider.
            required:
              - samlEntryPoint
              - samlIssuer
      responses:
        200:
          description: >-
            Success, returns updated SSO Config.
          schema:
            $ref: "#/definitions/SSOConfigResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update SSO config (full)
      tags: [ ssoconfig ]
      description: >-
        Update the specified SSO Config. If a field is not included in the query
        body, that field will be set to null or its default value.
      operationId: putSSOConfig
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              Configuration parameters to enable SSO in Refocus.
            properties:
              samlEntryPoint:
                type: string
                maxLength: 2082
                description: >
                  Identity Provider endpoint.
              samlIssuer:
                type: string
                maxLength: 2082
                description: >
                  Issuer string to supply to Identity Provider.
            required:
              - samlEntryPoint
              - samlIssuer
      responses:
        200:
          description: >-
            Success, returns updated SSO Config.
          schema:
            $ref: "#/definitions/SSOConfigResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects:
    x-swagger-router-controller: subjects
    get:
      security:
        - jwt: []
      summary: Find subjects
      tags: [ subjects ]
      description: >-
        Find a subject or subjects. You may query using field filters with
        asterisk (*) wildcards. You may also optionally specify sort, limit,
        offset, and a list of fields to include in the response. The global
        default limit will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /subjects
        url: http://focus.salesforce.com/docs/api/subjects
      operationId: findSubjects
      parameters:
        -
          $ref: "#/parameters/SubjectsFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - absolutePath
              - description
              - helpEmail
              - helpUrl
              - id
              - isPublished
              - name
              - sortBy
              - parentAbsolutePath
              - parentId
              #- childCount
              - createdBy
              - createdAt
              - updatedAt
              - -absolutePath
              - -description
              - -helpEmail
              - -helpUrl
              - -id
              - -isPublished
              - -name
              - -sortBy
              - -parentAbsolutePath
              - -parentId
              #- -childCount
              - -createdBy
              - -createdAt
              - -updatedAt
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: absolutePath
          in: query
          description: >-
            Filter by absolutePath; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: description
          in: query
          description: >-
            Filter by description; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: helpEmail
          in: query
          description: >-
            Filter by helpEmail; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: helpUrl
          in: query
          description: >-
            Filter by helpUrl; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: imageUrl
          in: query
          description: >-
            Filter by imageUrl; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: isPublished
          in: query
          description: >-
            Filter by isPublished (true|false).
          required: false
          type: boolean
        -
          name: name
          in: query
          description: >-
            Filter by name; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: sortBy
          in: query
          description: >-
            The sortBy string can be used to define the sort order of subjects
            which a lens developer can choose to honor when rendering the data.
            The attribute is defaulted to an empty string when the user does not
            provide any string value. Max 254 characters; case insensitive;
            allows alpha-numeric characters, + underscore (_) and dash (-).
            Filter by sortBy; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: parentAbsolutePath
          in: query
          description: >-
            Filter by parentAbsolutePath; asterisk (*) wildcards ok.
          required: false
          type: string
          maxLength: 4096
        -
          name: tags
          in: query
          items:
            type: string
            maxLength: 60
            pattern: ^[0-9A-Za-z_-]{1,60}$
          description: >-
             Comma-separated list of tags to include/exclude. Tag names are
             case-insensitive. For example, ?tags=FOO,BAR will only return
             subjects with tags FOO or BAR. Prefix each of the tag name with
             a negative sign to indicate that a subject with that tag should
             be excluded. For example, ?tags=-BAZ,-FOO will return only the
             subjects with tag name not equal to BAZ or FOO. Subjects without
             tags are not included in the result set.
          type: array
          required: false
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when subjects were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when subjects were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, a list of subjects.
          schema:
            type: array
            items:
              $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create subject
      tags: [ subjects ]
      description: >-
        Create a new subject. If you are creating a new subject as the child of another subject AND any of its ancestors has isPublished=false, then you must create your new subject with isPublished=false.
      operationId: postSubject
      parameters:
        -
          name: queryBody
          in: body
          schema:
            type: object
            description: >
              A resource under observation.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the subject. A lens may choose to display this
                  information to the user.
              helpEmail:
                type: string
                description: >
                  The email address where a user can go to get more help about the
                  subject. A lens may choose to display this information to the user e.g.
                  if the user clicks a “help” icon attached to the subject.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >
                  The url where a user can go to get more help about the subject. A lens
                  may choose to display this information to the user e.g. if the user
                  clicks a “help” icon attached to the subject.
              imageUrl:
                type: string
                maxLength: 2082
                description: >
                  Optional icon to represent the subject.
              isPublished:
                type: boolean
                default: false
                description: >
                  Default false. When set to true, the subject is readable by other users;
                  when set to false, the subject is only readable by its owner. You can only unpublish a subject if it has no subject children of its own or if all its descendants are unpublished.
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              sortBy:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{0,254}$
                maxLength: 254
                description: >
                  The sortBy string can be used to define the sort order of subjects
                  which a lens developer can choose to honor when rendering the data.
                  The attribute is defaulted to an empty string when the user does not
                  provide any string value. Max 254 characters; case insensitive;
                  allows alpha-numeric characters, + underscore (_) and dash (-).
                  Filter by sortBy; asterisk (*) wildcards ok.
                  Max 254 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              parentId:
                type: string
                pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
                description: >
                  The id of the subject's parent.
              tags:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-). Tag names cannot start with a dash (-).
              relatedLinks:
                type: array
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              geolocation:
                type: array
                items:
                  type: number
                description: >
                  If the subject has a physical location, specify its longitude and latitude in this two-element array, e.g. [-122.431297, 37.773972]. The first element in the array represents longitude; the second element represents latitude.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}:
    x-swagger-router-controller: subjects
    delete:
      security:
        - jwt: []
      summary: Delete subject
      tags: [ subjects ]
      description: >-
        Delete the specified subject. You will not be allowed to delete a
        subject if it has any children subjects under it. Beware! Deleting a
        subject also deletes all the samples associated with this subject.
      operationId: deleteSubject
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns deleted subject.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get subject
      tags: [ subjects ]
      description: >-
        Retrieve the specified subject by its id or name. You may also
        optionally specify a list of fields to include in the response.
      operationId: getSubject
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/SubjectsFieldsParam"
      responses:
        200:
          description: >-
            Success, returns specified subject.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update subject (partial)
      tags: [ subjects ]
      description: >-
        Update the specified subject. If a field is not included in the query
        body, that field will not be updated. You can only unpublish a subject if it has no subject children of its own or if all its descendants are unpublished. Beware! Updating a subject's name/parentId/parentAbsolutePath deletes all the samples associated with this subject.
      operationId: patchSubject
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              A resource under observation.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the subject. A lens may choose to display this
                  information to the user.
              helpEmail:
                type: string
                description: >
                  The email address where a user can go to get more help about the
                  subject. A lens may choose to display this information to the user e.g.
                  if the user clicks a “help” icon attached to the subject.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >
                  The url where a user can go to get more help about the subject. A lens
                  may choose to display this information to the user e.g. if the user
                  clicks a “help” icon attached to the subject.
              imageUrl:
                type: string
                maxLength: 2082
                description: >
                  Optional icon to represent the subject.
              isPublished:
                type: boolean
                default: false
                description: >
                  Default false. When set to true, the subject is readable by other users;
                  when set to false, the subject is only readable by its owner. You can only unpublish a subject if it has no subject children of its own or if all its descendants are unpublished.
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              sortBy:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{0,254}$
                maxLength: 254
                description: >
                  The sortBy string can be used to define the sort order of subjects
                  which a lens developer can choose to honor when rendering the data.
                  The attribute is defaulted to an empty string when the user does not
                  provide any string value. Max 254 characters; case insensitive;
                  allows alpha-numeric characters, + underscore (_) and dash (-).
                  Filter by sortBy; asterisk (*) wildcards ok.
                  Max 254 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              parentAbsolutePath:
                type: string
                maxLength: 4096
                description: >
                  The absolutePath of the subject's parent.
              parentId:
                type: string
                pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
                description: >
                  The id of the subject's parent.
              tags:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-). Tag names cannot start with a dash (-).
              relatedLinks:
                type: array
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              geolocation:
                type: array
                items:
                  type: number
                description: >
                  If the subject has a physical location, specify its longitude and latitude in this two-element array, e.g. [-122.431297, 37.773972]. The first element in the array represents longitude; the second element represents latitude.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it

      responses:
        200:
          description: >-
            Success, returns updated subject.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update subject (full)
      tags: [ subjects ]
      description: >-
        Update the specified subject. If a field is not included in the query
        body, that field will be set to null or its default value. You can only unpublish a subject if it has no subject children of its own or if all its descendants are unpublished. Beware! Updating a subject's name/parentId/parentAbsolutePath deletes all the samples associated with this subject.
      operationId: putSubject
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              A resource under observation.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the subject. A lens may choose to display this
                  information to the user.
              helpEmail:
                type: string
                description: >
                  The email address where a user can go to get more help about the subject.
                  A lens may choose to display this information to the user e.g. if the
                  user clicks a “help” icon attached to the subject.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >
                  The url where a user can go to get more help about the subject. A lens
                  may choose to display this information to the user e.g. if the user
                  clicks a “help” icon attached to the subject.
              imageUrl:
                type: string
                maxLength: 2082
                description: >
                  Optional icon to represent the subject.
              isPublished:
                type: boolean
                default: false
                description: >
                  Default false. When set to true, the subject is readable by other users;
                  when set to false, the subject is only readable by its owner. You can only unpublish a subject if it has no subject children of its own or if all its descendants are unpublished.
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              sortBy:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{0,254}$
                maxLength: 254
                description: >
                  The sortBy string can be used to define the sort order of subjects
                  which a lens developer can choose to honor when rendering the data.
                  The attribute is defaulted to an empty string when the user does not
                  provide any string value. Max 254 characters; case insensitive;
                  allows alpha-numeric characters, + underscore (_) and dash (-).
                  Filter by sortBy; asterisk (*) wildcards ok.
                  Max 254 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              parentId:
                type: string
                pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
                description: >
                  The id of the subject's parent.
              parentAbsolutePath:
                type: string
                maxLength: 4096
                description: >
                  The absolutePath of the subject's parent.
              tags:
                type: array
                default: []
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-). Tag names cannot start with a dash (-).
              relatedLinks:
                type: array
                default: []
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
              geolocation:
                type: array
                items:
                  type: number
                description: >
                  If the subject has a physical location, specify its longitude and latitude in this two-element array, e.g. [-122.431297, 37.773972]. The first element in the array represents longitude; the second element represents latitude.
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
      responses:
        200:
          description: >-
            Success, returns updated subject.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}/child:
    x-swagger-router-controller: subjects
    post:
      security:
        - jwt: []
      summary: Create child subject
      tags: [ subjects ]
      description: >-
        Create a new child subject of the specified subject. If any of your new subject's ancestors has isPublished=false, then you must create your new subject with isPublished=false.
      operationId: postChildSubject
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject to which you want to add a
            child.
          required: true
          type: string
        -
          name: queryBody
          description: Request body
          in: body
          schema:
            type: object
            description: >
              A resource under observation.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the subject. A lens may choose to display this
                  information to the user.
              helpEmail:
                type: string
                description: >
                  The email address where a user can go to get more help about the
                  subject. A lens may choose to display this information to the user e.g.
                  if the user clicks a “help” icon attached to the subject.
                maxLength: 254
              helpUrl:
                type: string
                maxLength: 2082
                description: >
                  The url where a user can go to get more help about the subject. A lens
                  may choose to display this information to the user e.g. if the user
                  clicks a “help” icon attached to the subject.
              imageUrl:
                type: string
                maxLength: 2082
                description: >
                  Optional icon to represent the subject.
              isPublished:
                type: boolean
                default: false
                description: >
                  Default false. When set to true, the subject is readable by other users;
                  when set to false, the subject is only readable by its owner. You can only unpublish a subject if it has no subject children of its own or if all its descendants are unpublished.
              name:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{1,60}$
                maxLength: 60
                description: >
                  Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              sortBy:
                type: string
                pattern: ^[0-9A-Za-z_\\-]{0,254}$
                maxLength: 254
                description: >
                  The sortBy string can be used to define the sort order of subjects
                  which a lens developer can choose to honor when rendering the data.
                  The attribute is defaulted to an empty string when the user does not
                  provide any string value. Max 254 characters; case insensitive;
                  allows alpha-numeric characters, + underscore (_) and dash (-).
                  Filter by sortBy; asterisk (*) wildcards ok.
                  Max 254 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-).
              tags:
                type: array
                items:
                  type: string
                  maxLength: 60
                  pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
                description: >
                  Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
                  underscore (_) and dash (-). Tag names cannot start with a dash (-).
              relatedLinks:
                type: array
                items:
                  $ref: "#/definitions/RelatedLinkRequest"
                description: >
                  RelatedLinks associated with this model.
            required:
              - name
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}/hierarchy:
    x-swagger-router-controller: subjects
    delete:
      security:
        - jwt: []
      summary: Delete subject hierarchy
      tags: [ subjects ]
      description: >-
        Delete the specified subject and all its descendents and all associated
        samples.
      operationId: deleteSubjectHierarchy
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the root subject to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns empty object.
          schema: {}
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get subject hierarchy
      tags: [ subjects ]
      description: >-
        Retrieve the hierarchy for the specified subject using its id or
        absolute path.
      operationId: getSubjectHierarchy
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the root subject to retrieve.
          required: true
          type: string
        -
          name: depth
          in: query
          description: >-
            The number of hierarchy levels to include (0 for all, 1 for
            just children, 2 for children and grandchildren, etc.).
          type: integer
          minimum: 0
        -
          name: aspect
          in: query
          description: >-
           Comma-separated list of aspect names to include/exclude.
           For example, ?aspect=FOO,BAR will only return subjects in the
           hierarchy with samples for those two aspects (and all those
           subjects' ancestors up to the specified root of the requested
           hierarchy). Prefix each of the aspect name with a negative sign to
           indicate that a sample with that aspect should be excluded.
           For example, ?aspect=-BAZ,-FOO will return only the subjects
           (and its hierarchy) that have samples with aspect name not equal
           to BAZ or FOO. Subjects without samples are not included in the
           result set
          type: string
        -
          name: status
          in: query
          description: >-
           Comma-separated list of sample status to include/exclude.
           For example, ?status=OK,CRITICAL will only return subjects in the
           hierarchy with samples that are in those statuses (and all those
           subjects' ancestors up to the specified root of the requested
           hierarchy). Prefix each of the status with a negative sign to
           indicate that a sample with that status should be excluded.
           For example, ?status=-OK,-CRITICAL will return only the subjects
           (and its hierarchy) that have samples not in OK or CRITICAL status.
           Subjects without samples are not included in the result set
          type: string
        -
          name: aspectTags
          in: query
          description: >-
           Comma-separated list of tags names to include/exclude.
           For example, ?aspectTags=TAG1,TAG2 will only return subjects in the
           hierarchy with samples having aspect with tags matching TAG1 and TAG2
           (and all those subjects' ancestors up to the specified root of the
           requested hierarchy). Prefix each of the tag names with a negative
           sign to indicate that a sample having aspect with those tag names
           will be excluded. For example, ?aspectTags=-TAG3,-TAG4 will
           return the subject hierarchy without aspects having tags -
           TAG3 and TAG4. Subjects without samples are not included in
           the result set
          type: string
        -
          name: subjectTags
          in: query
          description: >-
           Comma-separated list of tags names to include/exclude.
           For example, ?subjectTags=TAG1,TAG2 will only return subjects in the
           hierarchy with tags matching TAG1 and TAG2
           (and all those subjects' ancestors up to the specified root of the
           requested hierarchy). Prefix each of the tag names with a negative
           sign to indicate that the subject having tags with those names will
           be excluded. For example, ?subjectTags=-TAG3,-TAG4 will return the
           subject hierarchy without subjects having tags -  TAG3 and TAG4.
           Tags should be passed as an include filter or as an exclude filter
           but not the combination of both.
          type: string
        -
          $ref: "#/parameters/SubjectsFieldsParam"
      responses:
        200:
          description: >-
            Success, returns specified subject heirarchy.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}/tags:
    x-swagger-router-controller: subjects
    delete:
      security:
        - jwt: []
      summary: Delete subject tags
      tags: [ subjects ]
      description: >-
        Delete all the tags associated with the subject.
      operationId: deleteSubjectTags
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject for which tags needs to be
            deleted.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns updated subject
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}/tags/{tagName}:
    x-swagger-router-controller: subjects
    delete:
      security:
        - jwt: []
      summary: Delete subject tag
      tags: [ subjects ]
      description: >-
        Delete the specified tag of the specified subject.
      operationId: deleteSubjectTags
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject for which tag needs to be
            deleted.
          required: true
          type: string
        -
          name: tagName
          in: path
          description: >-
            Name of tag which needs to be deleted.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns updated subject.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}/relatedLinks:
    x-swagger-router-controller: subjects
    delete:
      security:
        - jwt: []
      summary: Delete subject related links
      tags: [ subjects ]
      description: >-
        Delete all the tags associated with the subject.
      operationId: deleteSubjectRelatedLinks
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject for which related links needs
            to be deleted.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns updated subject.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}/relatedLinks/{relName}:
    x-swagger-router-controller: subjects
    delete:
      security:
        - jwt: []
      summary: Delete subject related link
      tags: [ subjects ]
      description: >-
        Delete the specified related link of the specified subject.
      operationId: deleteSubjectRelatedLinks
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or absolute path of the subject for which related link needs
            to be deleted.
          required: true
          type: string
        -
          name: relName
          in: path
          description: >-
            Name of the related link which needs to be deleted.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns updated subject.
          schema:
            $ref: "#/definitions/SubjectsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}/writers:
    x-swagger-router-controller: subjects
    delete:
      security:
        - jwt: []
      summary: Delete subject writers
      tags: [ subjects ]
      description: >-
        Remove all users from a subject’s list of authorized writers.
      operationId: deleteSubjectWriters
      parameters:
        -
          name: key
          in: path
          description: >-
             The id or name of the subject.
          required: true
          type: string
      responses:
        204:
          description: >-
            The subject is no longer write-protected.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get subject writers
      tags: [ subjects ]
      description: >-
        Get the list of all authorized writers for a subject.
      operationId: getSubjectWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the subject for which the authorized list of users
            are to be obtained.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the users having write permission to the subject.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
              description: >-
                The users having write permission to the subject
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Add subject writer
      tags: [ subjects ]
      description: >-
        Add one or more users to a subjects list of authorized writers.
      operationId: postSubjectWriters
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the subject for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              User name
      responses:
        201:
          description: >-
            One or more of the valid users were added to the list of authorized writers.
          schema:
            type: array
            items:
              $ref: "#/definitions/SubjectWriterResponse"
              description: >-
                The users having write permission to the subject
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/{key}/writers/{userNameOrId}:
    x-swagger-router-controller: subjects
    delete:
      security:
        - jwt: []
      summary: Delete subject writer
      tags: [ subjects ]
      description: >-
        Remove a user from a subjects's list of authorized writers.
      operationId: deleteSubjectWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the subject
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        204:
          description: >-
            The user’s write permission has been revoked for the subject.
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get subject writer
      tags: [ subjects ]
      description: >-
        Determine whether a user is an authorized writer for subject.
      operationId: getSubjectWriter
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the subject for which the authorized list of users
            are to be obtained.
          required: true
          type: string
        -
          name: userNameOrId
          in: path
          description: >-
            The username or the Id of the user
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, return authorized user
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /tokens:
    x-swagger-router-controller: tokens
    post:
      security:
        - jwt: []
      summary: Create access token
      tags: [ tokens ]
      description: >-
        Create a new API access token by providing a token in header.
      operationId: postToken
      parameters:
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              Name of token.
            properties:
              name:
                type: string
                maxLength: 60
                description: >
                  A name for your new token. Token name must be unique for a
                  user. Best practice is to select a name which reminds you of
                  how you intend to use the token,
                  e.g. "PushSamplesFromSystemXyz".
            required:
              - name
      responses:
        201:
          description: Token created.
          schema:
            $ref: "#/definitions/TokenResponse"
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        403:
          description: >-
            Caller is not authorized to create token. While your authentication
            is valid, the authenticated user or token does not have permission
            to perform this action.
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
              $ref: '#/definitions/ErrorResponse'

  # ---------------------------------------------------------------------------
  /tokens/{key}:
    x-swagger-router-controller: tokens
    delete:
      security:
        - jwt: []
      summary: Delete access token
      tags: [ tokens ]
      description: >-
        Delete the specified token by its id.
      operationId: deleteTokenById
      parameters:
        -
          name: key
          in: path
          description: >-
            The id of the token to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the metadata for the deleted token.
          schema:
            $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        403:
          description: >-
            Caller is not authorized to delete token. While your authentication
            is valid, the authenticated user or token does not have permission
            to perform this action.
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'
    get:
      security:
        - jwt: []
      summary: Get access token
      tags: [ tokens ]
      description: >-
        Retrieve metadata about the specified token by its id. You may also
        optionally specify a list of fields to include in the response.
      operationId: getTokenByKey
      parameters:
        -
          name: key
          in: path
          description: >-
            The id of the token to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/TokensFieldsParam"
      responses:
        200:
          description: Success, returns metadata about the specified token.
          schema:
            $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'

  # ---------------------------------------------------------------------------
  /tokens/{key}/revoke:
    x-swagger-router-controller: tokens
    post:
      security:
        - jwt: []
      summary: Revoke access token
      tags: [ tokens ]
      description: >-
        Revoke access for the specified token.
      operationId: revokeTokenById
      parameters:
        -
          name: key
          in: path
          description: >-
            The id of the token to delete.
          required: true
          type: string
      responses:
        200:
          description: Success, token permission revoked.
          schema:
            $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments, e.g. trying to revoke a token which had already
            been revoked. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'

  # ---------------------------------------------------------------------------
  /tokens/{key}/restore:
    x-swagger-router-controller: tokens
    post:
      security:
        - jwt: []
      summary: Restore revoked access token
      tags: [ tokens ]
      description: >-
        Restore access for the specified token if access had previously been
        revoked.
      operationId: restoreTokenById
      parameters:
        -
          name: key
          in: path
          description: >-
            The id of the token to delete.
          required: true
          type: string
      responses:
        200:
          description: Success, token permission restored.
          schema:
            $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments, e.g. trying to restore a token which had not
            been revoked. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'

  # ---------------------------------------------------------------------------
  /users:
    x-swagger-router-controller: users
    get:
      security:
        - jwt: []
      summary: Find users
      tags: [ users ]
      description: >-
        Find a user or users. You may query using field filters with asterisk
        (*) wildcards. You may also optionally specify sort, limit, offset, and
        a list of fields to include in the response. The global default limit
        will apply if no limit param is specified.
      externalDocs:
        description: >-
          GET /users
        url: http://focus.salesforce.com/docs/api/users
      operationId: findUsers
      parameters:
        -
          $ref: "#/parameters/UsersFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - email
              - id
              - name
              - fullName
              - createdBy
              - createdAt
              - updatedAt
              - -email
              - -id
              - -name
              - -fullName
              - -createdBy
              - -createdAt
              - -updatedAt
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: email
          in: query
          description: >-
            Filter by email; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: name
          in: query
          description: >-
            Filter by name; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: createdAt
          in: query
          description: >-
            Filter by time period when users were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        -
          name: updatedAt
          in: query
          description: >-
            Filter by time period when users were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: >-
            Success, a list of users.
          schema:
            type: array
            items:
              $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        default:
          $ref: "#/responses/genericError"
    post:
      security:
        - jwt: []
      summary: Create user
      tags: [ users ]
      description: >-
        Create a new user.
      operationId: postUser
      parameters:
        -
          name: queryBody
          in: body
          schema:
            type: object
            description: >
              A person or API client who interacts with the Refocus system.
            properties:
              email:
                type: string
                maxLength: 254
                description: >
                  The user's email address.
              imageUrl:
                type: string
                maxLength: 2082
                description: >
                  Optional thumbnail image.
              name:
                type: string
                maxLength: 256
                description: >
                  First and last name.
              fullName:
                type: string
                maxLength: 256
                description: >
                  The user's full name.
              password:
                type: string
            required:
              - name
      responses:
        201:
          description: >-
            Success, returns created user.
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /users/{key}:
    x-swagger-router-controller: users
    delete:
      security:
        - jwt: []
      summary: Delete user
      tags: [ users ]
      description: >-
        Delete the specified user. An admin user may delete any user;
        non-admin users may only delete themselves. Beware! Deleting a user
        also deletes all the perspectives associated with this user.
      operationId: deleteUser
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the user to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns deleted user.
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    get:
      security:
        - jwt: []
      summary: Get user
      tags: [ users ]
      description: >-
        Retrieve the specified user by its id or name. You may also optionally
        specify a list of fields to include in the response.
      operationId: getUser
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the user to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/UsersFieldsParam"
      responses:
        200:
          description: >-
            Success, returns specified user.
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update user (partial)
      tags: [ users ]
      description: >-
        Update the specified user. If a field is not included in the query body,
        that field will not be updated.
      operationId: patchUser
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the user to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              A person or API client who interacts with the Refocus system.
            properties:
              email:
                type: string
                maxLength: 254
                description: >
                  The user's email address.
              imageUrl:
                type: string
                maxLength: 2082
                description: >
                  Optional thumbnail image.
              name:
                type: string
                maxLength: 256
                description: >
                  First and last name.
              fullName:
                type: string
                maxLength: 256
                description: >
                  The user's full name.
              password:
                type: string
      responses:
        200:
          description: >-
            Success, returns updated user.
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update user (full)
      tags: [ users ]
      description: >-
        Update the specified user. If a field is not included in the query body,
        that field will be set to null or its default value.
      operationId: putUser
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the user to update.
          required: true
          type: string
        -
          name: queryBody
          in: body
          required: true
          schema:
            type: object
            description: >
              A person or API client who interacts with the Refocus system.
            properties:
              email:
                type: string
                maxLength: 254
                description: >
                  The user's email address.
              imageUrl:
                type: string
                maxLength: 2082
                description: >
                  Optional thumbnail image.
              name:
                type: string
                maxLength: 256
                description: >
                  First and last name.
              fullName:
                type: string
                maxLength: 256
                description: >
                  The user's full name.
              password:
                type: string
              profileId:
                type: string
            required:
              - name
      responses:
        200:
          description: >-
            Success, returns updated user.
          schema:
            $ref: "#/definitions/UsersResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /users/{key}/tokens:
    x-swagger-router-controller: userTokens
    get:
      security:
        - jwt: []
      summary: Get user access token
      tags: [ users ]
      description: >-
        Retrieve metadata about the users' tokens. You may also optionally
        specify a list of fields to include in the response.
      operationId: getUserTokens
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or username of the user whose tokens you to retrieve. User
            IDs are case-sensitive.
          required: true
          type: string
        -
          $ref: "#/parameters/TokensFieldsParam"
      responses:
        200:
          description: >-
            Success, returns a list of tokens.
          schema:
            type: array
            items:
              $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'

  # ---------------------------------------------------------------------------
  /users/{key}/tokens/{tokenName}:
    x-swagger-router-controller: userTokens
    delete:
      security:
        - jwt: []
      summary: Delete user access token
      tags: [ users ]
      description: >-
        Given a user name and token name, delete the specified token.
      operationId: deleteUserToken
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the user. User IDs are case-sensitve.
          required: true
          type: string
        -
          name: tokenName
          in: path
          description: >-
            The name of the token to delete.
          required: true
          type: string
      responses:
        200:
          description: >-
            Success, returns the metadata for the deleted token.
          schema:
            $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        403:
          description: >-
            Caller is not authorized to delete token. While your authentication
            is valid, the authenticated user or token does not have permission
            to perform this action.
          schema:
            $ref: '#/definitions/ErrorResponse'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'
    get:
      security:
        - jwt: []
      summary: Retrieve user access token
      tags: [ tokens ]
      description: >-
        Retrieve metadata about the specified token. You may also optionally
        specify a list of fields to include in the response.
      operationId: getUserToken
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the user. User IDs are case-sensitve.
          required: true
          type: string
        -
          name: tokenName
          in: path
          description: >-
            The name of the token to delete.
          required: true
          type: string
        -
          $ref: "#/parameters/TokensFieldsParam"
      responses:
        200:
          description: Success, returns metadata about the specified token.
          schema:
            $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'

  # ---------------------------------------------------------------------------
  /users/{key}/tokens/{tokenName}/revoke:
    x-swagger-router-controller: userTokens
    post:
      security:
        - jwt: []
      summary: Revoke user access token
      tags: [ users ]
      description: >-
        Revoke access for the specified token.
      operationId: revokeTokenByName
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the user. User IDs are case-sensitve.
          required: true
          type: string
        -
          name: tokenName
          in: path
          description: >-
            The name of the token to delete.
          required: true
          type: string
      responses:
        200:
          description: Success, token permission revoked.
          schema:
            $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments, e.g. trying to revoke a token which had already
            been revoked. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'

  # ---------------------------------------------------------------------------
  /users/{key}/tokens/{tokenName}/restore:
    x-swagger-router-controller: userTokens
    post:
      security:
        - jwt: []
      summary: Restore revoked user access token
      tags: [ users ]
      description: >-
        Restore access for the specified token if access had previously been
        revoked.
      operationId: restoreTokenByName
      parameters:
        -
          name: key
          in: path
          description: >-
            The id or name of the user. User IDs are case-sensitve.
          required: true
          type: string
        -
          name: tokenName
          in: path
          description: >-
            The name of the token to delete.
          required: true
          type: string
      responses:
        200:
          description: Success, token permission restored.
          schema:
            $ref: "#/definitions/TokensResponse"
        400:
          description: >-
            Invalid arguments, e.g. trying to restore a token which had not
            been revoked. Please review the response for error details.
          schema:
            $ref: '#/definitions/BadRequest'
        401:
          description: >-
            Caller did not supply credentials or did not provide the correct
            credentials. If you are using an API key, it may be invalid or your
            Authorization header may be malformed.
          schema:
            $ref: '#/definitions/AuthenticationError'
        404:
          description: >-
            The resource you requested does not exist.
          schema:
            $ref: '#/definitions/ResourceNotFoundError'
        default:
          description: >-
            An unexpected error occurred. Please review the response for error
            details.
          schema:
            $ref: '#/definitions/ErrorResponse'

  # ---------------------------------------------------------------------------
  /subjects/delete/bulk:
    x-swagger-router-controller: subjects
    post:
      security:
        - jwt: []
      summary: Bulk subject delete
      tags: [ subjects ]
      description: >-
        Executes asynchronous bulk subject deletion.
      operationId: deleteSubjects
      produces:
        - text/plain; charset=utf-8
      parameters:
        -
          name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            description: >
              Array of strings where each string is a subject id or absolutePath.
      responses:
        200:
          description: >-
            Success, returns OK
          schema:
            $ref: "#/definitions/BulkSubjectDeleteResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /subjects/delete/bulk/{key}/status:
    x-swagger-router-controller: subjects
    get:
      security:
        - jwt: []
      summary: Bulk subject delete job status
      tags: [ subjects ]
      description: >-
        Retrieve the job status (and any errors) for the specified bulk subject delete job.
      operationId: getSubjectBulkDeleteStatus
      parameters:
        -
          name: key
          in: path
          description: >-
            The job id
          required: true
          type: integer
      responses:
        200:
          description: >-
            Success.
          schema:
            $ref: "#/definitions/GetBulkSubjectDeleteStatusResponse"
        400:
          $ref: "#/responses/400"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  # ---------------------------------------------------------------------------
  /collectorGroups:
    x-swagger-router-controller: collectorGroups
    post:
      security:
        - jwt: []
      summary: Create a new collector group
      tags: [ collectorGroups ]
      description: >-
        Create a new collector group if all the collectors aren't already assigned to a different group.
      operationId: createCollectorGroup
      parameters:
        - name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: object
            description: Create a collector group.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >-
                  A description of the collector group.
              name:
                type: string
                maxLength: 60
                description: A unique and descriptive name for the collector group.
              collectors:
                description: List of collectors for the group.
                type: array
                items:
                  type: string
              generators:
                description: List of generators assigned to this group.
                type: array
                items:
                  type: string
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name
      responses:
        201:
          description: >-
            Created.
          schema:
            $ref: "#/definitions/CollectorGroupsResponse"
        400:
          $ref: "#/responses/400"
        403:
          $ref: "#/responses/403"
        default:
          $ref: "#/responses/genericError"

    get:
      security:
        - jwt: []
      tags: [ collectorGroups ]
      summary: Find collectorGroups
      description: >-
        Find a collectorGroup or collectorGroups. You may query using field filters with
        asterisk (*) wildcards. You may also optionally specify sort, limit,
        offset, and a list of fields to include in the response. The global
        default limit will apply if no limit param is specified.
      operationId: findCollectorGroups
      parameters:
        -
          $ref: "#/parameters/CollectorGroupsFieldsParam"
        - name: sort
          in: query
          description: >
            Specify the sort order using a field name, e.g. '...?sort=name'. Prepend the
            field name with a minus sign to specify descending order, e.g.
            '...?sort=-name'.
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum:
              - name
              - description
              - -name
              - -description
        -
          $ref: "#/parameters/limitParam"
        -
          $ref: "#/parameters/offsetParam"
        -
          name: name
          in: query
          description: >-
            Filter by name; asterisk (*) wildcards ok.
          required: false
          type: string
        -
          name: description
          in: query
          description: >-
            Filter by description; asterisk (*) wildcards ok.
          required: false
          type: string
        - name: createdAt
          in: query
          description: >-
            Filter by time period when CollectorGroups were created.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
        - name: updatedAt
          in: query
          description: >-
            Filter by time period when CollectorGroups were updated.
          required: false
          type: string
          pattern: '^-\d+[smdh]$'
      responses:
        200:
          description: Success, returns an array of zero or more Refocus collectorGroups.
          schema:
            type: "array"
            items:
              $ref: "#/definitions/CollectorGroupsResponse"

  /collectorGroups/{key}:
    x-swagger-router-controller: collectorGroups
    get:
      security:
        - jwt: []
      tags: [ collectorGroups ]
      summary: Get collectorGroups
      description: >-
        Retrieve the specified collectorGroup metadata by the collectorGroups's id or name.
        You may also optionally specify a list of fields to include in the response.
      operationId: getCollectorGroup
      parameters:
        -
          name: key
          in: path
          description: The id or name of the collectorGroup to retrieve.
          required: true
          type: string
        -
          $ref: "#/parameters/CollectorGroupsFieldsParam"
      responses:
        200:
          description: Success, returns the specified collectorGroup's metadata.
          schema:
            $ref: "#/definitions/CollectorGroupsResponse"
        400:
          description: "Invalid ID supplied"
        404:
          description: "CollectorGroup not found"

    delete:
      security:
        - jwt: []
      summary: Delete collector group.
      tags: [ collectorGroups ]
      description: >-
        Delete collector group if it isn't in use by a Sample Generator.
      operationId: deleteCollectorGroup
      parameters:
        - name: key
          in: path
          description: >-
            The name of the collector group.
          required: true
          type: string
      responses:
        200:
          description: >-
            Deleted.
          schema:
            $ref: "#/definitions/CollectorGroupsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    patch:
      security:
        - jwt: []
      summary: Update collector group (partial).
      tags: [ collectorGroups ]
      description: >-
        Update the specified fields. If patching the list of collectors, it will replace the current list.
        It will update if all collectors named in the array aren't already assigned to a different group.
      operationId: patchCollectorGroup
      parameters:
        - name: key
          in: path
          description: The name of the collector group.
          required: true
          type: string
        - name: queryBody
          in: body
          description: Request body.
          required: true
          schema:
            type: object
            description: >
              A collector group.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the collector group.
              name:
                type: string
                maxLength: 60
                description: >
                  A unique and descriptive name for the collector group.
              collectors:
                description: List of collectors for the group.
                type: array
                items:
                  type: string
              generators:
                description: List of generators assigned to this group.
                type: array
                items:
                  type: string
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
      responses:
        200:
          description: Success, returns the updated collector group.
          schema:
            $ref: "#/definitions/CollectorGroupsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/404"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    put:
      security:
        - jwt: []
      summary: Update collector group.
      tags: [ collectorGroups ]
      description: >-
        Update all fields, replacing any existing values, and if a field is not provided, it resets to default
        (e.g. empty array of collectors, empty description).
      operationId: putCollectorGroup
      parameters:
        - name: key
          in: path
          description: The name of the collector group.
          required: true
          type: string
        - name: queryBody
          in: body
          description: Request body.
          required: true
          schema:
            type: object
            description: >
              A collector group.
            properties:
              description:
                type: string
                maxLength: 4096
                description: >
                  A description of the collector group.
              name:
                type: string
                maxLength: 60
                description: >
                  A unique and descriptive name for the collector group.
              collectors:
                description: List of collectors for the group.
                type: array
                items:
                  type: string
              generators:
                description: List of generators assigned to this group.
                type: array
                items:
                  type: string
              owner:
                type: string
                description: >
                  The name of the user to assign as the owner. Defaults to the user that created it
            required:
              - name

      responses:
        200:
          description: Success, returns the updated collector group.
          schema:
            $ref: "#/definitions/CollectorGroupsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/404"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

  /collectorGroups/{key}/collectors:
    x-swagger-router-controller: collectorGroups
    post:
      security:
        - jwt: []
      summary: Add a collector to the group
      tags: [ collectorGroups ]
      description: >-
        Add a collector to the group if any collector named in the array isn't already in the list or isn't already
        assigned to a different group.
      operationId: addCollectorsToGroup
      parameters:
        - name: key
          in: path
          description: >-
            The name of the collector group.
          required: true
          type: string
        - name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            minItems: 1
            uniqueItems: true
            description: >-
              List of collector names
      responses:
        200:
          description: >-
            One or more collectors were added to the group.
          schema:
            $ref: "#/definitions/CollectorGroupsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"
    delete:
      security:
        - jwt: []
      summary: Delete named collector(s) from group.
      tags: [ collectorGroups ]
      description: >-
        Delete named collector(s) from group. Reject if any named collector is not already associated with this group.
      operationId: deleteCollectorsFromGroup
      parameters:
        - name: key
          in: path
          description: >-
            The name of the collector group.
          required: true
          type: string
        - name: queryBody
          description: Request body.
          in: body
          required: true
          schema:
            type: array
            items:
              type: string
            minItems: 1
            uniqueItems: true
            description: >-
              List of collectors
      responses:
        200:
          description: Success, returns the updated collector group.
          schema:
            $ref: "#/definitions/CollectorGroupsResponse"
        400:
          $ref: "#/responses/400"
        401:
          $ref: "#/responses/401"
        403:
          $ref: "#/responses/403"
        404:
          $ref: "#/responses/404"
        default:
          $ref: "#/responses/genericError"

# =============================================================================
definitions:

  AuthenticationError:
    properties:
      errors:
        type: array
        items:
          type: object
    required:
      - errors

  BadRequest:
    properties:
      errors:
        type: array
        items:
          type: object
    required:
      - errors

  ErrorResponse:
    properties:
      errors:
        type: array
        items:
          type: object
    required:
      - errors
  #  required:
  #    - message

  HATEOAS:
    type: object
    description: >
      Hypertext As The Engine Of Application State.
    properties:
      href:
        type: string
        maxLength: 2082
        readOnly: true
        description: >
          URL of the related HATEOAS link you can use for subsequent calls.
      rel:
        type: string
        maxLength: 255
        readOnly: true
        description: >
          Link relation that describes how this link relates to the previous call.
      method:
        type: string
        readOnly: true
        maxLength: 255
        description: >
          The HTTP method required for the related call.
    required:
      - href
      - rel
      - method

  RelatedLinkResponse:
    type: object
    description: >
      RelatedLink that is associated with a model.
    properties:
      name:
        type: string
        maxLength: 60
        readOnly: true
        description: >
          Name of the related link.
      url:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          The relatedLink url. For example, a related link associated with a
          sample can have a link to the source from which that sample
          information is obtained.

  RelatedLinkRequest:
    type: object
    description: >
      RelatedLink that is associated with a model.
    properties:
      name:
        type: string
        minLength: 1
        maxLength: 60
        pattern: ^[0-9A-Za-z_\\ -]{1,60}$
        description: >
          Name of the related link.
      url:
        type: string
        minLength: 1
        maxLength: 4096
        description: >
          The relatedLink url. For example, a related link associated with a
          sample can have a link to the source from which that sample
          information is obtained.
    required:
      - name
      - url

  ResourceNotFoundError:
    properties:
      errors:
        type: array
        items:
          type: object
    required:
      - errors

    # properties:
    #   message:
    #     type: string
    #   resourceType:
    #     type: string
    #     enum:
    #       - Aspect
    #       - Lens
    #       - Perspective
    #       - Profile
    #       - Sample
    #       - Subject
    #       - User
    #   resourceKey:
    #     type: string
    # required:
    #   - message

  AspectsResponse:
    type: object
    description: >
      A type of observation which can be measured.
    properties:
      description:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          A description of the aspect. A lens may choose to display this
          information to the user.
      helpEmail:
        type: string
        readOnly: true
        maxLength: 254
        description: >
          The email address where a user can go to get more help about the aspect.
          A lens may choose to display this information to the user e.g. if the
          user clicks a “help” icon attached to the aspect.
      helpUrl:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          The url where a user can go to get more help about the aspect. A lens
          may choose to display this information to the user e.g. if the user
          clicks a “help” icon attached to the aspect.
      id:
        type: string
        readOnly: true
        description: >
          The aspect id.
      imageUrl:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          Optional icon to represent the aspect.
      isPublished:
        type: boolean
        default: false
        readOnly: true
        description: >
          This affects the visibility of samples; defaults to false. When set to
          true, all the samples for this aspect are readable by other users; when
          set to false, the samples for this aspect are only readable by the owner
          of the aspect.
      name:
        type: string
        readOnly: true
        maxLength: 60
        pattern: ^[0-9A-Za-z_\\-]{1,60}$
        description: >
          Max 60 characters; case insensitive; allows alpha-numeric characters,
          underscore (_) and dash (-).
      criticalRange:
        type: array
        items:
          type: number
        readOnly: true
        maxLength: 2
        minLength: 2
        example: [1,7]
        description: >
          A two-element array of type decimal. Determines what range of values
          should be assigned to status value 0.
      warningRange:
        type: array
        items:
          type: number
        readOnly: true
        maxLength: 2
        minLength: 2
        example: [1,7]
        description: >
          A two-element array of type decimal. Determines what range of values
          should be assigned to status value 1.
      infoRange:
        type: array
        items:
          type: number
        readOnly: true
        maxLength: 2
        minLength: 2
        example: [1,7]
        description: >
          A two-element array of type decimal. Determines what range of values
          should be assigned to status value 2.
      okRange:
        type: array
        items:
          type: number
        readOnly: true
        maxLength: 2
        minLength: 2
        example: [1,7]
        description: >
          A two-element array of type decimal. Determines what range of values
          should be assigned to status value 3.
      timeout:
        type: string
        readOnly: true
        maxLength: 8
        pattern: ^[0-9]+[smhdSMHD]$
        description: >
          The length of time after which a sample is treated as 'N/A', in the form
          of /^[0-9]+[smhd]$/i. For example, use '5s' for five seconds, '2m' for
          two minutes, '12h' for twelve hours, '1d' for one day.
      valueLabel:
        type: string
        readOnly: true
        maxLength: 10
        description: >
          A short label the lens may display next to the value. Most useful to
          specify a unit of measurement, e.g. 'ms' or '%'.
      valueType:
        type: string
        readOnly: true
        maxLength: 7
        enum:
          - BOOLEAN
          - NUMERIC
          - PERCENT
        default: BOOLEAN
        description: >
          The sample value must be able to be coerced to the specified data type.
          This allows a lens to render sample data in different ways depending on
          their type.
      createdBy:
        type: string
        readOnly: true
        description: >
          Id of the User who created this Aspect.
      createdAt:
        readOnly: true
        type: string
        description: >
          TODO
      updatedAt:
        readOnly: true
        type: string
        description: >
          TODO
      tags:
        type: array
        items:
          type: string
          maxLength: 60
          pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
        description: >
          Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
          underscore (_) and dash (-). Tag names cannot start with a dash (-).
      Samples:
        type: array
        readOnly: true
        description: >
          TODO
        items:
          $ref: "#/definitions/SamplesResponse"
      relatedLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/RelatedLinkResponse"
        description: >
          RelatedLinks associated with this model.
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  AuditEventsResponse:
    type: object
    description: >
      An auditable Refocus event.
    properties:
      details:
        type: object
        readOnly: true
        description: >
          A JSON object with additional event details.
      id:
        type: string
        readOnly: true
        description: >
          The auditEvent id.
      loggedAt:
        type: string
        readOnly: true
        description: >
          The timestamp when the event was logged.
      isError:
        type: boolean
        readOnly: true
        default: false
        description: >
          True if this audit event represents an error.
      resourceName:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          The name of the resource associated with this event.
      resourceType:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          The type of the resource associated with this event, e.g.
          "Collector", "Subject", etc.
      createdBy:
        type: string
        readOnly: true
        description: >
          Id of the User/Collector who created this auditEvent.
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp when the record was saved to Refocus. Due to latency and
          queuing, this value is expected to be greater than the loggedAt
          timestamp.
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  GlobalConfigResponse:
    type: object
    description: >
      A global configuration item (key/value pair).
    properties:
      key:
        type: string
        readOnly: true
        maxLength: 60
      value:
        type: string
        readOnly: true
      createdBy:
        type: string
        readOnly: true
        description: >
          User who created this Aspect.
      createdAt:
        readOnly: true
        type: string
        description: >
          TODO
      updatedAt:
        readOnly: true
        type: string
        description: >
          TODO
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  LensesResponse:
    type: object
    description: >
      A user interface component which renders subject/sample data with a
      particular visual representation.
    properties:
      description:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          A description of the lens.
      helpEmail:
        type: string
        readOnly: true
        description: >
          The email address where a user can go to get more help about the lens.
          A lens may choose to display this information to the user e.g. if the
          user clicks a "help" icon attached to the lens.
        maxLength: 254
      helpUrl:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          The url where a user can go to get more help about the lens. A lens may
          choose to display this information to the user e.g. if the user clicks a
          "help" icon attached to the lens.
      id:
        type: string
        readOnly: true
        description: >
          The lens id.
      isCustom:
        type: boolean
        readOnly: true
        default: true
        description: >
          True for any lens which is installed by an administrator (rather than
            pre-installed in Refocus).
      isPublished:
        type: boolean
        readOnly: true
        description: >
          True when the lens is available to users.
      lensEventApiVersion:
        description: >-
          The API version for the Lens Event API, e.g. 1, 2, etc.
        readOnly: true
        type: integer
        default: 1
      name:
        type: string
        maxLength: 60
        readOnly: true
        pattern: ^[0-9A-Za-z_\\-]{0,60}$
        description: >
          The name of lens. Max 60 characters; case insensitive;
          allows alpha-numeric characters, underscore (_) and dash (-).
      sourceDescription:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          The original lens publisher's description of the lens.
      sourceName:
        type: string
        maxLength: 60
        readOnly: true
        pattern: ^[0-9A-Za-z_\\-]{0,60}$
        description: >
          The original lens publisher's name of the lens.
      sourceVersion:
        type: string
        readOnly: true
        description: >
          The original lens publisher's version of the lens.
      thumbnailUrl:
        type: string
        maxLength: 2082
        readOnly: true
        description: >
          Optional thumbnail image to represent the lens.
      installedBy:
        readOnly: true
        type: string
        description: >
          TODO
      createdBy:
        type: string
        readOnly: true
        description: >
          Id of the User who created this Lens.
      createdAt:
        readOnly: true
        type: string
        description: >
          TODO
      updatedAt:
        readOnly: true
        type: string
        description: >
          TODO
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  PerspectivesResponse:
    type: object
    description: >
      A named combination of a set of subjects and their samples rendered by a
      particular lens.
    properties:
      id:
        type: string
        readOnly: true
      name:
        type: string
        readOnly: true
        pattern: ^[0-9A-Za-z_\\-]{1,60}$
        maxLength: 60
        description: >
          The name of the perspective.
      rootSubject:
        type: string
        maxLength: 4096
        description: >
          The absolute path of the root subject.
      aspectFilter:
        type: array
        items:
          type: string
          maxLength: 60
          pattern: ^[0-9A-Za-z_\\-]{1,60}$
        description: >
          Array of aspect names to filter; Aspect name: Max 60 characters; case insensitive; allows alpha-numeric characters,
          underscore (_) and dash (-).
      aspectTagFilter:
        type: array
        items:
          type: string
          maxLength: 60
          pattern: ^[0-9A-Za-z_\\-]{1,60}$
        description: >
          Array of aspect tag names to filter; Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
          underscore (_) and dash (-).
      subjectTagFilter:
        type: array
        items:
          type: string
          maxLength: 60
          pattern: ^[0-9A-Za-z_\\-]{1,60}$
        description: >
          Array of subject tag names to filter; Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
          underscore (_) and dash (-).
      aspectFilterType:
        type: string
        enum:
          - INCLUDE
          - EXCLUDE
      aspectTagFilterType:
        type: string
        enum:
          - INCLUDE
          - EXCLUDE
      subjectTagFilterType:
        type: string
        enum:
          - INCLUDE
          - EXCLUDE
      statusFilter:
        type: array
        items:
          type: string
          enum:
            - Critical
            - Invalid
            - Timeout
            - Warning
            - Info
            - OK
            - "-Critical"
            - "-Invalid"
            - "-Timeout"
            - "-Warning"
            - "-Info"
            - "-OK"
        description: >
          Array of sample status to filter; Status values can only be one of these:
          Critical, Invalid, Timeout, Warning, Info, OK, -Critical, -Invalid, -Timeout, -Warning, -Info, -OK.
      createdBy:
        readOnly: true
        type: string
        description: >
          TODO
      createdAt:
        readOnly: true
        type: string
        description: >
          TODO
      updatedAt:
        readOnly: true
        type: string
        description: >
          TODO
      lensId:
        type: string
        description: >
          The id of Lens.
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  ProfilesResponse:
    type: object
    description: >
      A named set of read/write privileges.
    properties:
      id:
        type: string
        readOnly: true
      name:
        type: string
        readOnly: true
        pattern: ^[0-9A-Za-z_\\-]{1,60}$
        maxLength: 60
        description: >
          The name of the profile.
      aspectAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write aspects.
      botAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write bots.
      eventAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write events.
      lensAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write lenses.
      perspectiveAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write perspectives.
      profileAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write profiles.
      roomAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: rw
        description: >
          The permission to read and/or write rooms.
      roomTypeAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write roomTypes.
      sampleAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write samples.
      subjectAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write subjects.
      userAccess:
        type: string
        readOnly: true
        maxLength: 2
        enum:
          - r
          - rw
        default: r
        description: >
          The permission to read and/or write users.
      users:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/UsersResponse"
      createdBy:
        readOnly: true
        type: string
        description: >
          TODO
      createdAt:
        readOnly: true
        type: string
        description: >
          TODO
      updatedAt:
        readOnly: true
        type: string
        description: >
          TODO
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  SamplesResponse:
    type: object
    description: >
      An observation of a particular aspect for a particular subject at a
      particular point in time.
    properties:
      messageBody:
        type: string
        readOnly: true
        description: >
          Optional message about the sample value. Informational only--not used to
          determine the status of the sample. It's up to the lens whether/how to
          display this, will typically be displayed only on hover or click.
        maxLength: 4096
      messageCode:
        type: string
        readOnly: true
        maxLength: 5
        description: >
          Optional 5-charater code about the sample value. Informational only--not
          used to determine the status of the sample. It's up to the lens
          whether/how to display this, will typically be displayed without having
          to hover or click.
      status:
        type: string
        enum:
          - Critical
          - Invalid
          - Timeout
          - Warning
          - Info
          - OK
        readOnly: true
        description: >
          Status.
      previousStatus:
        type: string
        enum:
          - Critical
          - Invalid
          - Timeout
          - Warning
          - Info
          - OK
        readOnly: true
        description: >
          Previous Status.
      value:
        type: string
        readOnly: true
        maxLength: 255
        description: >
          Stored as a string but will be treated as whatever the aspect’s
          valueType was specified as, i.e. [BOOLEAN|NUMERIC|PERCENT]. If timeout
          occurs, value is set to null.
      provider:
        readOnly: true
        type: string
        description: >
          User who provided this sample.
      createdAt:
        readOnly: true
        type: string
        description: >
          TODO
      updatedAt:
        readOnly: true
        type: string
        description: >
          TODO
      statusChangedAt:
        readOnly: true
        type: string
        description: >
          Time at which the status changed from one state to another.
      relatedLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/RelatedLinkResponse"
        description: >
          RelatedLinks associated with this model.
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  BulkUpsertResponse:
    type: object
    description: >
      Status of bulk upsert request.
    properties:
      status:
        type: string
        enum:
          - OK
        readOnly: true
        description: >
          Status.
      jobId:
        type: integer
        readOnly: true
        description: >
          Optionally a jobId is returned with the response when the bulk upsert
          request is enqueued as a job for the workers to process it
          asynchronously. The returned jobId can be used to check the status
          of the bulk upsert request.

  GetBulkUpsertStatusResponse:
    type: object
    description: >
      Status of bulk upsert request.
    properties:
      status:
        type: string
        readOnly: true
        maxLength: 254
        description: >
          Status.
      errors:
        type: array
        readOnly: true
        description: >
          An array containing the error information of the samples that
          were not upserted.
        items:
          type: object

  SubjectsResponse:
    type: object
    description: >
      A resource under observation.
    properties:
      absolutePath:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          The absolute path of the subject. This is automatically set based on the
          name and hierarchy.
      children:
        type: array
        items:
          $ref: "#/definitions/SubjectsResponse"
      description:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          A description of the subject. A lens may choose to display this
          information to the user.
      helpEmail:
        type: string
        readOnly: true
        maxLength: 254
        description: >
          The email address where a user can go to get more help about the subject.
          A lens may choose to display this information to the user e.g. if the
          user clicks a “help” icon attached to the subject.
      helpUrl:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          The url where a user can go to get more help about the subject. A lens
          may choose to display this information to the user e.g. if the user
          clicks a “help” icon attached to the subject.
      id:
        type: string
        readOnly: true
      imageUrl:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          Optional icon to represent the subject.
      isPublished:
        type: boolean
        readOnly: true
        description: >
          Default false. When set to true, the subject is readable by other users;
          when set to false, the subject is only readable by its owner.
      name:
        type: string
        readOnly: true
        pattern: ^[0-9A-Za-z_\\-]{1,60}$
        maxLength: 60
        description: >
          Max 60 characters; case insensitive; allows alpha-numeric characters,
          underscore (_) and dash (-).
      sortBy:
        type: string
        readOnly: true
        pattern: ^[0-9A-Za-z_\\-]{0,254}$
        maxLength: 254
        description: >
          The sortBy string can be used to define the sort order of subjects
          which a lens developer can choose to honor when rendering the data.
          The attribute is defaulted to an empty string when the user does not
          provide any string value. Max 254 characters; case insensitive;
          allows alpha-numeric characters, + underscore (_) and dash (-).
          Filter by sortBy; asterisk (*) wildcards ok.
          Max 254 characters; case insensitive; allows alpha-numeric characters,
          underscore (_) and dash (-).
      parentId:
        type: string
        readOnly: true
        description: >
          The id of the subject's parent, empty if this subject is at the root of
          the hierarchy.
      parentAbsolutePath:
        type: string
        readOnly: true
        maxLength: 4096
        description: >
          The absolute path of the subject's parent, empty if this subject is at
          the root of the hierarchy.
      # childCount:
      #   type: integer
      #   readOnly: true
      #   description: >
      #    The number of direct children subjects under this subject.
      createdBy:
        type: string
        readOnly: true
        description: >
          Id of the User who created this Aspect.
      createdAt:
        type: string
        readOnly: true
        description: >
          TODO
      updatedAt:
        type: string
        readOnly: true
        description: >
          TODO
      tags:
        type: array
        items:
          type: string
          maxLength: 60
          pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
        description: >
          Array of tag names. Tag name: Max 60 characters; case insensitive; allows alpha-numeric characters,
          underscore (_) and dash (-). Tag names cannot start with a dash (-).
      samples:
        type: array
        description: >
          TODO
        items:
          type: object
      relatedLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/RelatedLinkResponse"
        description: >
          RelatedLinks associated with this model.
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.
      hierarchyLevel:
        type: integer
        readOnly: true
        description: >
         The depth of the subject starting from the root. The root always has a
          hierarchy level of 1
  TokensResponse:
    type: object
    description: >
      Metadata about the JSON web token.
    properties:
      id:
        type: string
        readOnly: true
      isRevoked:
        type: string
        readOnly: true
        description: >
          Zero if the token is still active, non-zero if the token has been
          revoked.
      name:
        type: string
        readOnly: true
        maxLength: 60
        description: >
          The name of the token.
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  UsersResponse:
    type: object
    description: >
      A person or API client who interacts with the Refocus system.
    properties:
      email:
        type: string
        readOnly: true
        maxLength: 254
        description: >
          The user's email address.
      id:
        type: string
        readOnly: true
      imageUrl:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          Optional thumbnail image.
      name:
        type: string
        readOnly: true
        maxLength: 256
        description: >
          First and last name.
      fullName:
        type: string
        readOnly: true
        maxLength: 256
        description: >
          The user's full name.
      password:
        type: string
        readOnly: true
      createdBy:
        type: string
        readOnly: true
        description: >
          TODO
      createdAt:
        type: string
        readOnly: true
        description: >
          TODO
      updatedAt:
        type: string
        readOnly: true
        description: >
          TODO
      # TODO profile!
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  SSOConfigResponse:
    type: object
    description: >
      SSO Configuration parameters used to enable SSO in Refocus.
    properties:
      id:
        type: string
        readOnly: true
      samlEntryPoint:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          Required SAML Identity Provider entry point.
      samlIssuer:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          Required issuer string to supply to identity provider.
      createdBy:
        type: string
        readOnly: true
        description: >
          TODO
      createdAt:
        type: string
        readOnly: true
        description: >
          TODO
      updatedAt:
        type: string
        readOnly: true
        description: >
          TODO
      # TODO profile!
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  TokenResponse:
    type: object
    description: >
      API access token if authentication success.
    properties:
      Success:
        type: boolean
        readOnly: true
      id:
        type: string
      isDisabled:
        type: string
        readOnly: true
      name:
        type: string
        readOnly: true
        description:
          Name of token.
      token:
        type: string
        readOnly: true
        description: >
          API token.
      createdBy:
        readOnly: true
        type: string
        description: >
          TODO
      apiLinks:
        readOnly: true
        type: array
        items:
          $ref: "#/definitions/HATEOAS"
        description: >
          Hypertext As The Engine Of Application State.

  AuthenticationResponse:
    type: object
    description: >
      Authentication success response.
    properties:
      Success:
        type: boolean
        readOnly: true
      message:
        type: string
        readOnly: true
        maxLength: 2082
        description: >
          Authentication success message.

  AspectWriterResponse:
    type: object
    description: >
      Users having write permission to the aspects
    properties:
      aspectId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected aspect
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the aspect
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  GeneratorWriterResponse:
    type: object
    description: >
      Users having write permission to the generator
    properties:
      generatorId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected generator
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the generator
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  GeneratorTemplateWriterResponse:
    type: object
    description: >
      Users having write permission to the generatorTemplate
    properties:
      generatorTemplateId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected generatorTemplate
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the generatorTemplate
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  LensWriterResponse:
    type: object
    description: >
      Users having write permission to the lenses
    properties:
      lensId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected aspect
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the lens
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  PerspectiveWriterResponse:
    type: object
    description: >
      Users having write permission to the perspectives
    properties:
      perspectiveId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected perspective
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the perspective
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  SubjectWriterResponse:
    type: object
    description: >
      Users having write permission to the subject
    properties:
      subjectId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected subject
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the subject
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  BotActionWriterResponse:
    type: object
    description: >
      Users having write permission to the botAction
    properties:
      botActionId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected botAction
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the botAction
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  BotDataWriterResponse:
    type: object
    description: >
      Users having write permission to the botData
    properties:
      botDataId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected botData
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the botData
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  BotWriterResponse:
    type: object
    description: >
      Users having write permission to the bot
    properties:
      botId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected bot
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the bot
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  RoomWriterResponse:
    type: object
    description: >
      Users having write permission to the room
    properties:
      roomId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected room
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the room
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  RoomTypeWriterResponse:
    type: object
    description: >
      Users having write permission to the roomType
    properties:
      roomTypeId:
        type: string
        readOnly: true
        description: >
          Id of a write-protected roomType
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the roomType
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  BotResponse:
    type: object
    description: A response for information about a bot
    properties:
      id:
        type: string
        description: The UUID for the bot
      name:
        type: string
        description: The unique readable name for the bot
      url:
        type: string
        description: The URL of the bot server
      ui:
        type: object
        description: The UI of the bot
        properties:
          name:
            type: string
            description: The name of the UI file.
          size:
            type: integer
            description: The size of the UI file (bytes)
      active:
        type: boolean
        description: Flag for if a bot is active with communication
      actions:
        type: array
        description: A list of actions that a bot can perform
        items:
          type: object
      data:
        type: array
        description: A list of data that a bot can provide
        items:
          type: object
      installedBy:
        readOnly: true
        type: string
        description: >
          The user who installed the bot

  EventResponse:
    type: object
    description: A response for information about a event
    properties:
      id:
        type: string
        description: The UUID of the specified event
      log:
        type: string
        description: Human readable log line describing the event and its context it stores
      context:
        type: object
        description: A object, typically JSON, that contains the information to describe an event
      actionType:
        type: 'string'
        description: 'This is the type of the event'
      roomId:
        type: integer
        description: The room ID in which the event deals with
      botId:
        type: string
        description: The bot ID in which the event deals with
      botDataId:
        type: string
        description: The bot data ID in which the event deals with
      botActionId:
        type: string
        description: The bot action ID in which the event deals with
      userId:
        type: string
        description: The user ID in which the event deals with

  BulkCreateResponse:
    type: object
    description: >
      Status of bulk create request.
    properties:
      status:
        type: string
        enum:
          - OK
        readOnly: true
        description: >
          Status.

  BotActionResponse:
    type: object
    description: A response for information about bot actions
    properties:
      id:
        type: string
        description: The UUID of the specified bot action
      name:
        type: string
        description: The name of the bot action requested
      isPending:
        type: boolean
        description: If the action is still pending completion
      parameters:
        type: array
        description: The values required to run a bot action
        items:
          type: object
      response:
        type: object
        description: The output of an bot action
      roomId:
        type: integer
        description: The room ID in which the bot action deals with
      botId:
        type: string
        description: The bot ID in which the bot action deals with
      userId:
        type: string
        description: The user ID in which the bot action deals with

  CollectorResponse:
    type: "object"
    required:
    - "name"
    properties:
      id:
        type: string
        readOnly: true
        description: >
          The collector id.
      name:
        type: "string"
        description: "Should be unique."
      currentGenerators:
        readOnly: true
        type: "array"
        items:
          type: "object"
        description: "Generators assigned to this collector."
      registered:
        type: boolean
        description: "Boolean. If false, means deregistered. Changed by the DEREGISTER command"
        enum:
        - true
        - false
      status:
        type: "string"
        description: "The collector status."
        enum:
        - "Stopped"
        - "Running"
        - "Paused"
        - "MissedHeartbeat"
      lastHeartbeat:
        readOnly: true
        type: string
        description: >
          Timestamp at which the last heartbeat was sent.
      lastModifiedAt:
        readOnly: true
        type: string
        description: >
          Timestamp of the collector's most recent modification.
      createdBy:
        readOnly: true
        type: string
        description: >
          Id of the User who created this Collector.
      lastUpdatedBy:
        readOnly: true
        type: string
        description: >
          Timestamp of the collector's most recent update.
      description:
        type: string
        maxLength: 4096
        description: >
          Describes this Collector; helps a user determine which Collectors they should assign to run their collection.
      helpEmail:
        type: string
        description: >
          The email address where a user can go to get more help about the collector.
        maxLength: 254
      helpUrl:
        type: string
        maxLength: 2082
        description: >
          The url where a user can go to get more help about the collector.
      host:
        type: string
        description: >
          The host where the collector is installed.
        maxLength: 4096
      ipAddress:
        type: string
        description: >
          The ipAddress where the collector is installed.
        maxLength: 60
      collectorConfig:
        $ref: "#/definitions/CollectorConfigResponse"
      generatorsAdded:
        $ref: "#/definitions/GeneratorsAddedResponse"

  CollectorWriterResponse:
    type: object
    description: >
      Users having write permission to the collector
    properties:
      collectorId:
        type: string
        readOnly: true
        description: >
          Id of a collector
      userId:
        type: string
        readOnly: true
        description: >
          Id of a user having write permission to the collector
      createdAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was created
      updatedAt:
        readOnly: true
        type: string
        description: >
          Timestamp at which the the write permission was modified

  HeartbeatResponse:
    type: object
    description: >
      Gets the config and sample collection metadata from the Refocus server.
    properties:
      collectorConfig:
        $ref: "#/definitions/CollectorConfigResponse"
      generatersAdded:
        $ref: "#/definitions/GeneratorsAddedResponse"
      generatersUpdated:
        $ref: "#/definitions/GeneratorsUpdatedResponse"
      generatorsRemoved:
        $ref: "#/definitions/GeneratorsRemovedResponse"

  CollectorConfigResponse:
    type: object
    description: Collector config variables changed since last heartbeat.
    properties:
      heartbeatInterval:
        type: integer
        description: >
          The number of milliseconds to wait before aborting a request to Refocus.
      sampleCollectorTimeout:
        type: integer
        description: >-
          The number of milliseconds to wait before aborting a request to a remote data source.
          This value may be overridden by each Generator.
      sampleUpsertQueueTime:
        type: integer
        description: >-
          The maximum number of milliseconds that samples will wait before being sent to Refocus.
          When samples are returned by Generator transform, the Collector enqueues those samples
          to send as part of a larger bulk upsert to Refocus. In order to manage upsert load, a
          system-wide minimum sample upsert queue time will be defined in Refocus config;
          a Refocus admin will also be able to override that with a MINIMUM_SAMPLE_UPSERT_QUEUE_TIME
          environment variable.
      requireSslToRemoteDataSource:
        type: boolean
        description: >-
          Default false. Refocus Collector will accept only external sources as HTTPS when set as true.
  GeneratorsAddedResponse:
    type: array
    description: >-
      List of generators assigned to this agent since last heartbeat.
      New generator templates are included as well.
    items:
      $ref: "#/definitions/HeartbeatGeneratorResponse"

  GeneratorsUpdatedResponse:
    type: array
    description: >-
      List of generators assigned to this agent, but were modified
      since last heartbeat.
    items:
      $ref: "#/definitions/HeartbeatGeneratorResponse"

  GeneratorsRemovedResponse:
    readOnly: true
    type: array
    description: >
      List of generators which used to be assigned to this agent but is
      no longer assigned to this agent. Array of generator names.
    items:
      type: string

  GeneratorResponse:
    type: object
    description: >-
      The designation of which subjects and aspects to collect, plus any additional context data
    properties:
      description:
        type: string
        maxLength: 4096
        description: >
          A description of the generator.
      helpEmail:
        type: string
        description: >
          The email address where a user can go to get more help about the generator.
        maxLength: 254
      helpUrl:
        type: string
        maxLength: 2082
        description: >
          The url where a user can go to get more help about the generator.
      createdBy:
        readOnly: true
        type: string
        description: >
          Id of the User who created this Generator.
      id:
        type: string
        readOnly: true
        description: >
          The collector id.
      intervalSecs:
        type: integer
        description: >-
          Interval (seconds) between each collection.
      isActive:
        type: boolean
        description: Default false. When set to true, the generator will be assigned to a running collector and regularly send in samples.
      name:
        type: string
        readOnly: true
        description: The generator's name.
      subjectQuery:
        type: string
        readOnly: true
        minLength: 7
        maxLength: 4096
        description: The query to append to GET subjects. Only "absolutePath", "name", "tags" are allowed in subjectQuery.
      collectorGroup:
         description: Specifies set of collectors this Sample Generator should try to use.
         type: object
      aspects:
        description: Names of the aspects.
        type: array
        items:
          type: string
      tags:
        type: array
        items:
          type: string
          maxLength: 60
          pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
        description: >
          Array of tag names. Tag name: Max 60 characters; case insensitive;
          allows alpha-numeric characters, underscore (_) and dash (-). Tag
          names cannot start with a dash (-).
      connection:
        type: object
        description: Information about the connection.
      context:
        type: object
        description: >
          Variables accessible inside the transform function.
      currentCollector:
        type: object
        description: Current collector assigned to the generator.
        maxLength: 60
      generatorTemplate:
        $ref: "#/definitions/GeneratorTemplateResponse"

  HeartbeatGeneratorResponse:
    type: object
    description: >-
      The designation of which subjects and aspects to collect, plus any additional context data
    properties:
      description:
        type: string
        maxLength: 4096
        description: >
          A description of the generator.
      helpEmail:
        type: string
        description: >
          The email address where a user can go to get more help about the generator.
        maxLength: 254
      helpUrl:
        type: string
        maxLength: 2082
        description: >
          The url where a user can go to get more help about the generator.
      createdBy:
        readOnly: true
        type: string
        description: >
          Id of the User who created this Generator.
      id:
        type: string
        readOnly: true
        description: >
          The collector id.
      intervalSecs:
        type: integer
        description: >-
          Interval (seconds) between each collection.
      isActive:
        type: boolean
        description: Default false. When set to true, the generator will be assigned to a running collector and regularly send in samples.
      name:
        type: string
        readOnly: true
        description: The generator's name.
      subjectQuery:
        type: string
        readOnly: true
        minLength: 7
        maxLength: 4096
        description: The query to append to GET subjects. Only "absolutePath", "name", "tags" are allowed in subjectQuery.
      collectorGroup:
         description: Specifies set of collectors this Sample Generator should try to use.
         type: object
      aspects:
        description: Array of aspects.
        type: array
        items:
          type: object
      tags:
        type: array
        items:
          type: string
          maxLength: 60
          pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
        description: >
          Array of tag names. Tag name: Max 60 characters; case insensitive;
          allows alpha-numeric characters, underscore (_) and dash (-). Tag
          names cannot start with a dash (-).
      connection:
        type: object
        description: Information about the connection.
      context:
        type: object
        description: >
          Variables accessible inside the transform function.
      currentCollector:
        type: object
        description: Current collector assigned to the generator.
        maxLength: 60
      generatorTemplate:
        $ref: "#/definitions/GeneratorTemplateResponse"

  GeneratorTemplateResponse:
    type: object
    description: >-
      The transform logic and the definition of what additional context data is required.
    properties:
      description:
        type: string
        maxLength: 4096
        description: >-
          A description of the generatorTemplate.
      helpEmail:
        type: string
        description: >-
          The email address where a user can go to get more help about the
          generatorTemplate.
        maxLength: 254
      helpUrl:
        type: string
        maxLength: 2082
        description: >-
          The url where a user can go to get more help about the generatorTemplate.
      name:
        type: string
        readOnly: true
        description: >-
          The generatorTemplate's name.
      version:
        type: string
        description: >-
          The version, in semantic versioning format ( MAJOR.MINOR.PATCH )
      tags:
        type: array
        items:
          type: string
          maxLength: 60
          pattern: ^[0-9A-Za-z_][0-9A-Za-z_\\-]{1,59}$
        description: >-
          Array of tag names. Tag name: Max 60 characters; case insensitive;
          allows alpha-numeric characters, underscore (_) and dash (-). Tag
          names cannot start with a dash (-).
      author:
        type: object
        description: >-
          The author of this generatorTemplate.
      repository:
        type: object
        description: >-
          The repository where this generatorTemplate is located.
      connection:
        type: object
        description: >-
          Information about the connection.
      contextDefinition:
        type: object
        description: >-
          Variables available to connection.url, connection.toUrl, and
          the transform function.
      transform:
        type: object
        description: >-
          The body of a javascript function which transforms some data into an
          array of samples
      isPublished:
        type: boolean
        description: >-
          Default false. When set to true, the generatorTemplate is available to
          all users.
        default: false
      id:
        type: string
        readOnly: true
        description: >
          The generatorTemplate id.
      createdBy:
        type: string
        readOnly: true
        description: >
          Id of the User who created this generatorTemplate.


  RoomResponse:
    type: object
    description: A response for information about a room
    properties:
      id:
        type: integer
        description: The room number of the specified room
      name:
        type: string
        description: The unique readable name for the room
      active:
        type: boolean
        description: Flag for whether the room is still active or closed
      type:
        type: string
        description: The roomType being used in the specified room
      createdBy:
        type: string
        readOnly: true
        description: >
          Id of the User who created this room.
      origin:
        type: string
        description: Tracks where refocus room was created from

  RoomTypeResponse:
    type: object
    description: A response for information about a bot
    properties:
      id:
        type: string
        description: The UUID of the roomType specified
      name:
        type: string
        description: The roomType being used in the specified room
      isEnabled:
        type: boolean
        description: Flag indicating whether a roomType is enabled to use on rooms
      settings:
        type: object
        description: Key-value pairs used to configure bots and rooms intial state
      rules:
        type: array
        items:
          type: object
        description: Array containing the rules that trigger automations for rooms of this type
      bots:
        type: array
        items:
          type: string
        description: Array containing the bots to be used for rooms of this type
      createdBy:
        type: string
        readOnly: true
        description: >
          Id of the User who created this roomType.

  BotDataResponse:
    type: object
    description: A response for information about a room
    properties:
      id:
        type: string
        description: UUID of the specified bot data
      name:
        type: string
        description: Name of the bot data
      value:
        type: string
        description: Current value of the bot data
      roomId:
        type: integer
        description: The room number of the room of the bot data
      botId:
        type: string
        description: UUID of the specified bot in that room
      createdBy:
        type: string
        readOnly: true
        description: >
          Id of the User who created this botData.

  BulkSubjectDeleteResponse:
    type: object
    description: >
      Status of bulk subject delete request.
    properties:
      status:
        type: string
        enum:
          - OK
        readOnly: true
        description: >
          Status of the operation.
      jobId:
        type: integer
        readOnly: true
        description: >
          Optionally a jobId is returned with the response when the bulk subject
          delete request is enqueued as a job for the workers to process it
          asynchronously. The returned jobId can then be used to check the status of the bulk subject delete request.

  GetBulkSubjectDeleteStatusResponse:
    type: object
    description: >
      Status of the bulk subject delete request.
    properties:
      status:
        type: string
        readOnly: true
        maxLength: 254
        description: >
          Status.
      errors:
        type: array
        readOnly: true
        description: >
          An array of errors, if any errors were encountered while attempting to bulk delete subjects.
        items:
          type: object

  CollectorGroupsResponse:
    type: object
    description: >-
      The group of collectors
    properties:
      description:
        type: string
        maxLength: 4096
        description: >
          A description of the collector group.
      createdBy:
        readOnly: true
        type: string
        description: >
          Id of the user who created the collector group.
      id:
        type: string
        readOnly: true
        description: >
          The collector group id.
      name:
        type: string
        readOnly: true
        description: The collector group name.
      collectors:
        description: List of collectors for the group.
        type: array
        items:
          type: object

# =============================================================================
parameters:

  CollectorFieldsParam:
    name: fields
    in: query
    description: >
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - name
        - id
        - status
        - registered
        - currentGenerators
        - collectorGroup
        - lastHeartbeat
        - lastModifiedAt
        - createdBy
        - lastUpdatedBy
        - description
        - helpEmail
        - helpUrl
        - host
        - ipAddress
        - osInfo
        - processInfo
        - version
        - user
        - owner

  limitParam:
    name: limit
    in: query
    description: >
        Maximum number of records to return in the response; also useful for
        pagination in the UI.
    required: false
    type: integer

  offsetParam:
    name: offset
    in: query
    description: >
        Offset for paginating the response.
    required: false
    type: integer

  AspectsFieldsParam:
    name: fields
    in: query
    description: >
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - createdAt
        - criticalRange
        - description
        - helpEmail
        - helpUrl
        - id
        - imageUrl
        - infoRange
        - isPublished
        - name
        - okRange
        - rank
        - relatedLinks
        - tags
        - timeout
        - updatedAt
        - valueLabel
        - valueType
        - warningRange
        - user
        - owner

  AuditEventsFieldsParam:
    name: fields
    in: query
    description: >
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - createdAt
        - details
        - isError
        - loggedAt
        - resourceName
        - resourceType

  GeneratorFieldsParam:
    name: fields
    in: query
    description: >
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - isActive
        - tags
        - aspects
        - subjectQuery
        - createdAt
        - description
        - helpEmail
        - helpUrl
        - id
        - intervalSecs
        - name
        - updatedAt
        - currentCollector
        - user
        - owner
        - collectorGroup

  GeneratorTemplateFieldsParam:
    name: fields
    in: query
    description: >
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - description
        - helpEmail
        - helpUrl
        - id
        - name
        - version
        - tags
        - author
        - repository
        - connection
        - contextDefinition
        - transform
        - isPublished
        - user
        - owner

  LensesFieldsParam:
    name: fields
    in: query
    description: >
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - createdAt
        - description
        - helpEmail
        - helpUrl
        - id
        - installedBy
        - isCustom
        - isPublished
        - lensEventApiVersion
        - name
        - sourceDescription
        - sourceName
        - sourceVersion
        - thumbnailUrl
        - updatedAt
        - version
        - user
        - owner

  PerspectivesFieldsParam:
    name: fields
    in: query
    description: >
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - createdAt
        - createdBy
        - aspectFilter
        - aspectFilterType
        - aspectTagFilter
        - aspectTagFilterType
        - id
        - lensId
        - name
        - rootSubject
        - statusFilter
        - statusFilterType
        - subjectTagFilter
        - subjectTagFilterType
        - updatedAt
        - user
        - owner
        - lens

  ProfilesFieldsParam:
    name: fields
    in: query
    description: >-
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - id
        - name
        - aspectAccess
        - botAccess
        - eventAccess
        - lensAccess
        - perspectiveAccess
        - profileAccess
        - roomAccess
        - roomTypeAccess
        - sampleAccess
        - subjectAccess
        - userAccess
        - createdBy
        - createdAt
        - updatedAt
        - userCount
        - users

  SamplesFieldsParam:
    name: fields
    in: query
    description: >-
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - createdAt
        - id
        - messageBody
        - messageCode
        - name
        - previousStatus
        - provider
        - relatedLinks
        - status
        - statusChangedAt
        - tags
        - updatedAt
        - value

  SubjectsFieldsParam:
    name: fields
    in: query
    description: >-
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - absolutePath
        - createdAt
        - createdBy
        - description
        - geolocation
        - helpEmail
        - helpUrl
        - id
        - imageUrl
        - isPublished
        - name
        - sortBy
        - tags
        - parentAbsolutePath
        - parentId
        - relatedLinks
        - updatedAt
        - user
        - owner

  TokensFieldsParam:
    name: fields
    in: query
    description: >-
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - name
        - isRevoked
        - user

  UsersFieldsParam:
    name: fields
    in: query
    description: >-
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - email
        - id
        - imageUrl
        - name
        - createdBy
        - createdAt
        - sso
        - updatedAt
        - profile

  CollectorGroupsFieldsParam:
    name: fields
    in: query
    description: >-
      Comma-delimited list of field names to include in the response.
    required: false
    type: array
    collectionFormat: csv
    items:
      type: string
      enum:
        - name
        - description
        - createdAt
        - updatedAt
        - user
        - owner
        - collectors
        - generators

# =============================================================================
responses:
  400:
    description: Bad Request
    schema:
      $ref: '#/definitions/BadRequest'
  401:
    description: Authentication Error
    schema:
      $ref: '#/definitions/AuthenticationError'
  403:
    description: Forbidden
    schema:
      $ref: '#/definitions/ErrorResponse'
  404:
    description: Resource Not Found
    schema:
      $ref: '#/definitions/ResourceNotFoundError'
  genericError:
    description: Error
    schema:
      $ref: '#/definitions/ErrorResponse'