openapi: 3.0.1
info:
  title: Risks API
  description: Provides access to the risks that are part of a Hyperproof organization.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/risks
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/risks
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/risks
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    get:
      summary: Get Risks
      description: >
        `GET /`


        #### Description


        Retrieves details of all risks within an organization, including their
        descriptions, categories, likelihoods, and impacts. Note that only
        active risks are returned.
      operationId: get-risks
      parameters:
        - name: riskRegisterId
          in: query
          description: Unique ID of the risk register
          schema:
            type: string
        - name: status
          in: query
          description: >-
            Comma separated list of statuses to filter risks. Supported values:
            active, archived
          schema:
            type: string
        - name: expand
          in: query
          description: >-
            Comma separated list of fields to expand. Supported values:
            linkedControls.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  riskIdentifier: FGSC-RA1
                  riskRegisterId: 9f25da4f-1532-11ee-a87d-8e36b9d27de7
                  name: >-
                    Free Gas Safety Checks not provided in a complete and timely
                    manner
                  description: >-
                    Requests from eligible customers for a Free Gas Safety Check
                    are not actioned in an appropriate timescale leading to poor
                    customer service, the potential for safety issues and non
                    compliance with our SLCs.
                  category: Controls Program - Customer Operations
                  response: accept
                  responseRationale: accepted
                  likelihoodLevel: 1
                  likelihoodRationale: security
                  impactLevel: 1
                  impactRationale: cyber
                  notes: Reviewed by our internal team
                  ownerId: ce83e3cd-5199-11ee-a644-522476618aek
                  toleranceLevel: 1
                  overrideActualRisk: false
                  overrideActualRiskReason: low
                  overrideActualRiskBy: ac57e976-69ab-11ed-b991-1284f382c88o
                  overrideActualRiskOn: '2023-08-10T20:27:32.8901160+00:00'
                  actualRisk: 4
                  overrideResidualLikelihood: false
                  residualLikelihoodLevel: 3
                  overrideResidualLikelihoodBy: ac57e976-69ab-12ab-b991-1284f382c88a
                  overrideResidualLikelihoodOn: '2023-08-10T20:27:32.8901160+00:00'
                  overrideResidualImpact: true
                  residualImpactLevel: 2
                  overrideResidualImpactBy: ac57e976-69ab-11ed-b991-1284f382c88d
                  overrideResidualImpactOn: '2023-08-10T20:27:32.8901160+00:00'
                  customFields:
                    - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                      fieldName: Sponsor
                      fieldType: text
                      textValue: John Smith
                  status: active
                  createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  createdOn: '2023-09-12T18:26:10.0053650+00:00'
                  updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                  permissions: []
    post:
      summary: Add Risk
      description: >
        `POST /`


        #### Description


        Creates a new risk within an organization, capturing details such as
        title, description, category, and severity for risk management.
      operationId: add-risk
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskPost'
            example:
              riskRegisterId: 23b806fb-bad2-4f7a-b8d1-ac1177909992
              riskIdentifier: RA-5
              name: Gas Risk
              description: Risks of gas and electricity
              category: Controls Program - Customer Operations
              response: accept
              likelihoodLevel: 1
              likelihoodRationale: security
              impactLevel: 1
              impactRationale: cyber
              toleranceLevel: 1
              ownerId: 23b806db-bad2-4f7a-b8d1-ac117790999b
              customFields:
                - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                  textValue: Antonio Moreno
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Risk'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                riskIdentifier: FGSC-RA1
                riskRegisterId: 9f25da4f-1532-11ee-a87d-8e36b9d27de7
                name: >-
                  Free Gas Safety Checks not provided in a complete and timely
                  manner
                description: >-
                  Requests from eligible customers for a Free Gas Safety Check
                  are not actioned in an appropriate timescale leading to poor
                  customer service, the potential for safety issues and non
                  compliance with our SLCs.
                category: Controls Program - Customer Operations
                response: accept
                responseRationale: accepted
                likelihoodLevel: 1
                likelihoodRationale: security
                impactLevel: 1
                impactRationale: cyber
                notes: Reviewed by our internal team
                ownerId: ce83e3cd-5199-11ee-a644-522476618aek
                toleranceLevel: 1
                overrideActualRisk: false
                overrideActualRiskReason: low
                overrideActualRiskBy: ac57e976-69ab-11ed-b991-1284f382c88o
                overrideActualRiskOn: '2023-08-10T20:27:32.8901160+00:00'
                actualRisk: 4
                overrideResidualLikelihood: false
                residualLikelihoodLevel: 3
                overrideResidualLikelihoodBy: ac57e976-69ab-12ab-b991-1284f382c88a
                overrideResidualLikelihoodOn: '2023-08-10T20:27:32.8901160+00:00'
                overrideResidualImpact: true
                residualImpactLevel: 2
                overrideResidualImpactBy: ac57e976-69ab-11ed-b991-1284f382c88d
                overrideResidualImpactOn: '2023-08-10T20:27:32.8901160+00:00'
                customFields:
                  - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                    fieldName: Sponsor
                    fieldType: text
                    textValue: John Smith
                status: active
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
  /filter:
    put:
      summary: Get Risks Filtered
      description: >
        `PUT /risks/filter`


        #### Description


        Retrieves a list of risks that match the specified filter criteria, such
        as category, status, likelihood, or owner.
      operationId: get-risks-filtered
      parameters:
        - name: expand
          in: query
          description: >-
            Comma separated list of fields to expand. Supported values:
            linkedControls.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskFilter'
            example:
              riskIds:
                - 23b806db-bad2-4f7a-b8d1-ac1177909992
                - 23b402db-bad2-4f7a-b8d1-ac1177909992
              modifiedAfter: '2020-12-17T20:00:00.0000000+00:00'
              status: active
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  riskIdentifier: FGSC-RA1
                  riskRegisterId: 9f25da4f-1532-11ee-a87d-8e36b9d27de7
                  name: >-
                    Free Gas Safety Checks not provided in a complete and timely
                    manner
                  description: >-
                    Requests from eligible customers for a Free Gas Safety Check
                    are not actioned in an appropriate timescale leading to poor
                    customer service, the potential for safety issues and non
                    compliance with our SLCs.
                  category: Controls Program - Customer Operations
                  response: accept
                  responseRationale: accepted
                  likelihoodLevel: 1
                  likelihoodRationale: security
                  impactLevel: 1
                  impactRationale: cyber
                  notes: Reviewed by our internal team
                  ownerId: ce83e3cd-5199-11ee-a644-522476618aek
                  toleranceLevel: 1
                  overrideActualRisk: false
                  overrideActualRiskReason: low
                  overrideActualRiskBy: ac57e976-69ab-11ed-b991-1284f382c88o
                  overrideActualRiskOn: '2023-08-10T20:27:32.8901160+00:00'
                  actualRisk: 4
                  overrideResidualLikelihood: false
                  residualLikelihoodLevel: 3
                  overrideResidualLikelihoodBy: ac57e976-69ab-12ab-b991-1284f382c88a
                  overrideResidualLikelihoodOn: '2023-08-10T20:27:32.8901160+00:00'
                  overrideResidualImpact: true
                  residualImpactLevel: 2
                  overrideResidualImpactBy: ac57e976-69ab-11ed-b991-1284f382c88d
                  overrideResidualImpactOn: '2023-08-10T20:27:32.8901160+00:00'
                  customFields:
                    - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                      fieldName: Sponsor
                      fieldType: text
                      textValue: John Smith
                  status: active
                  createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  createdOn: '2023-09-12T18:26:10.0053650+00:00'
                  updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                  permissions: []
  /{riskId}:
    get:
      summary: Get Risk
      description: >
        `GET /{riskId}`


        #### Description


        Retrieves details of a specific risk in an organization by its ID,
        including its description, category, likelihood, and impact.
      operationId: get-risk
      parameters:
        - name: riskId
          in: path
          description: Unique ID of the risk.
          required: true
          schema:
            type: string
        - name: expand
          in: query
          description: >-
            Comma separated list of fields to expand. Supported values:
            linkedControls.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Risk'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                riskIdentifier: FGSC-RA1
                riskRegisterId: 9f25da4f-1532-11ee-a87d-8e36b9d27de7
                name: >-
                  Free Gas Safety Checks not provided in a complete and timely
                  manner
                description: >-
                  Requests from eligible customers for a Free Gas Safety Check
                  are not actioned in an appropriate timescale leading to poor
                  customer service, the potential for safety issues and non
                  compliance with our SLCs.
                category: Controls Program - Customer Operations
                response: accept
                responseRationale: accepted
                likelihoodLevel: 1
                likelihoodRationale: security
                impactLevel: 1
                impactRationale: cyber
                notes: Reviewed by our internal team
                ownerId: ce83e3cd-5199-11ee-a644-522476618aek
                toleranceLevel: 1
                overrideActualRisk: false
                overrideActualRiskReason: low
                overrideActualRiskBy: ac57e976-69ab-11ed-b991-1284f382c88o
                overrideActualRiskOn: '2023-08-10T20:27:32.8901160+00:00'
                actualRisk: 4
                overrideResidualLikelihood: false
                residualLikelihoodLevel: 3
                overrideResidualLikelihoodBy: ac57e976-69ab-12ab-b991-1284f382c88a
                overrideResidualLikelihoodOn: '2023-08-10T20:27:32.8901160+00:00'
                overrideResidualImpact: true
                residualImpactLevel: 2
                overrideResidualImpactBy: ac57e976-69ab-11ed-b991-1284f382c88d
                overrideResidualImpactOn: '2023-08-10T20:27:32.8901160+00:00'
                customFields:
                  - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                    fieldName: Sponsor
                    fieldType: text
                    textValue: John Smith
                status: active
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
    patch:
      summary: Update Risk
      description: >
        `PATCH /{riskId}`


        #### Description


        Updates an existing risk with new values, allowing modifications to its
        attributes such as description, status, likelihood, or impact.
      operationId: patch-risk
      parameters:
        - name: riskId
          in: path
          description: Unique ID of the risk to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RiskPatch'
            example:
              riskRegisterId: 23b806fb-bad2-4f7a-b8d1-ac1177909992
              riskIdentifier: RA-5
              name: Gas Risk
              description: Risks of gas and electricity
              category: Controls Program - Customer Operations
              response: accept
              ownerId: 23b806db-bad2-4f7a-b8d1-ac117790999b
              status: archived
              customFields:
                - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                  textValue: Antonio Moreno
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Risk'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                riskIdentifier: FGSC-RA1
                riskRegisterId: 9f25da4f-1532-11ee-a87d-8e36b9d27de7
                name: >-
                  Free Gas Safety Checks not provided in a complete and timely
                  manner
                description: >-
                  Requests from eligible customers for a Free Gas Safety Check
                  are not actioned in an appropriate timescale leading to poor
                  customer service, the potential for safety issues and non
                  compliance with our SLCs.
                category: Controls Program - Customer Operations
                response: accept
                responseRationale: accepted
                likelihoodLevel: 1
                likelihoodRationale: security
                impactLevel: 1
                impactRationale: cyber
                notes: Reviewed by our internal team
                ownerId: ce83e3cd-5199-11ee-a644-522476618aek
                toleranceLevel: 1
                overrideActualRisk: false
                overrideActualRiskReason: low
                overrideActualRiskBy: ac57e976-69ab-11ed-b991-1284f382c88o
                overrideActualRiskOn: '2023-08-10T20:27:32.8901160+00:00'
                actualRisk: 4
                overrideResidualLikelihood: false
                residualLikelihoodLevel: 3
                overrideResidualLikelihoodBy: ac57e976-69ab-12ab-b991-1284f382c88a
                overrideResidualLikelihoodOn: '2023-08-10T20:27:32.8901160+00:00'
                overrideResidualImpact: true
                residualImpactLevel: 2
                overrideResidualImpactBy: ac57e976-69ab-11ed-b991-1284f382c88d
                overrideResidualImpactOn: '2023-08-10T20:27:32.8901160+00:00'
                customFields:
                  - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
                    fieldName: Sponsor
                    fieldType: text
                    textValue: John Smith
                status: active
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            risk.read: Grants read access to risks
            risk.update: Grants update access to risks
  schemas:
    Risk:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the risk
        orgId:
          type: string
          format: uuid
          description: The unique identifier for the organization
        riskIdentifier:
          type: string
          description: >-
            Human readable unique identifier for the risk within the
            organization
        riskRegisterId:
          type: string
          format: uuid
          description: >-
            The unique identifier for the risk register which the risk belongs
            to
        name:
          type: string
          description: Name of the risk
        description:
          type: string
          description: Description of the risk
        category:
          type: string
          description: Category of the risk
        health:
          type: string
          enum:
            - healthy
            - atRisk
            - critical
          description: Current health status of the risk
        response:
          $ref: '#/components/schemas/RiskResponse'
        responseRationale:
          type: string
          description: Reasoning for the selected risk response
        riskStage:
          $ref: '#/components/schemas/RiskStage'
        notes:
          type: string
          description: Additional notes about the risk
        ownerId:
          type: string
          format: uuid
          description: The unique identifier for the user who is the owner of the risk
        groupId:
          type: string
          format: uuid
          description: The unique identifier of the group assigned to the risk
        riskReporterId:
          type: string
          format: uuid
          description: >-
            The unique identifier for the hyperproof user or external contact
            who reported the risk
        riskReporterType:
          type: string
          enum:
            - user
            - externalContact
          description: The type of person who reported the risk
        likelihoodLevel:
          type: integer
          description: The inherent likelihood level of the risk. Index notation (0-based)
        likelihoodValue:
          type: integer
          description: >-
            The user-assigned value for the inherent likelihood scale for the
            risk, determined from likelihoodLevel and customRiskScales
        likelihoodRationale:
          type: string
          description: The reasoning for the inherent likelihood level of the risk
        impactLevel:
          type: integer
          description: The inherent impact level of the risk. Index notation (0-based)
        impactRationale:
          type: string
          description: The reasoning for the inherent impact level of the risk
        impactValue:
          type: integer
          description: >-
            The user-assigned value of inherent impact scale for the risk,
            determined from impactLevel and customRiskScales
        inherentRisk:
          type: integer
          description: >-
            The inherent risk value for the risk, calculated as likelihoodValue
            x impactValue
        toleranceLevel:
          type: integer
          description: The tolerance level for the risk. Index notation (0-based)
        actualRisk:
          type: integer
          description: The user-overridden residual risk value for the risk
        overrideActualRisk:
          type: boolean
          description: >-
            Flag indicating whether the actual residual risk has been overridden
            from the calculated value
        overrideActualRiskReason:
          type: string
          description: The reasoning for overriding the residual risk
        overrideActualRiskBy:
          type: string
          description: The unique identifier of the user who overrode the residual risk
        overrideActualRiskOn:
          type: string
          format: date-time
          description: The date when the residual risk was overridden (ISO-8601 format)
        overrideResidualLikelihood:
          type: boolean
          description: >-
            Flag indicating whether the residual likelihood has been overridden
            from the calculated value
        residualLikelihoodLevel:
          type: integer
          description: >-
            The user-overridden residual likelihood level of the risk. Index
            notation (0-based)
        overrideResidualLikelihoodBy:
          type: string
          description: >-
            The unique identifier of the user who overrode the residual
            likelihood
        overrideResidualLikelihoodOn:
          type: string
          format: date-time
          description: >-
            The date when the residual likelihood was overridden (ISO-8601
            format)
        overrideResidualImpact:
          type: boolean
          description: >-
            Flag indicating whether the residual impact has been overridden from
            the calculated value
        residualImpactLevel:
          type: integer
          description: >-
            The user-overridden residual impact level of the risk. Index
            notation (0-based)
        overrideResidualImpactBy:
          type: string
          description: The unique identifier of the user who overrode the residual impact
        overrideResidualImpactOn:
          type: string
          format: date-time
          description: The date when the residual impact was overridden (ISO-8601 format)
        actualLikelihood:
          type: number
          format: double
          description: >-
            The residual likelihood value for the risk after applying the
            mitigation from linked controls and accounting for the controls'
            health to likelihoodValue. If overridden, calculated using
            residualLikelihoodLevel and customRiskScales
        actualImpact:
          type: number
          format: double
          description: >-
            The residual impact value for the risk after applying the mitigation
            from linked controls and accounting for the controls' health to
            impactValue. If overridden, calculated using residualImpactLevel and
            customRiskScales
        desiredResidualRisk:
          type: number
          format: double
          description: >-
            The calculated risk value after applying the mitigation from linked
            controls to the inherent risk value
        calculatedActualResidualRisk:
          type: number
          format: double
          description: >-
            The desiredResidualRisk accounting for the health of the mitigating
            controls
        actualResidualRisk:
          type: number
          format: double
          description: >-
            The calculatedActualResidualRisk value unless overridden by the
            actualRisk value
        customRiskScales:
          $ref: '#/components/schemas/CustomRiskScales'
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValue'
        status:
          $ref: '#/components/schemas/ObjectStatus'
        createdBy:
          type: string
          description: The unique identifier of the user who created the risk
        createdOn:
          type: string
          format: date-time
          description: The date the risk was created (ISO-8601 format)
        updatedBy:
          type: string
          description: The unique identifier of the user who last updated the risk
        updatedOn:
          type: string
          format: date-time
          description: The date the risk was updated (ISO-8601 format)
        permissions:
          type: array
          description: List of permissions the API user has on the risk
          items:
            type: string
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        riskIdentifier: FGSC-RA1
        riskRegisterId: 9f25da4f-1532-11ee-a87d-8e36b9d27de7
        name: Free Gas Safety Checks not provided in a complete and timely manner
        description: >-
          Requests from eligible customers for a Free Gas Safety Check are not
          actioned in an appropriate timescale leading to poor customer service,
          the potential for safety issues and non compliance with our SLCs.
        category: Controls Program - Customer Operations
        health: atRisk
        response: accept
        riskStage: operating
        responseRationale: accepted
        likelihoodLevel: 1
        likelihoodRationale: security
        likelihoodValue: 2
        impactLevel: 2
        impactRationale: cyber
        impactValue: 5
        inherentRisk: 10
        notes: Reviewed by our internal team
        ownerId: ce83e3cd-5199-11ee-a644-522476618aek
        groupId: d2363cab-5199-11ee-a644-522476618ae8
        riskReporterId: ce83e3cd-5484-11ee-12b6-522476618ae9
        riskReporterType: externalContact
        toleranceLevel: 1
        overrideActualRisk: 'false'
        overrideActualRiskReason: low
        overrideActualRiskBy: ac57e976-69ab-11ed-b991-1284f382c88o
        overrideActualRiskOn: '2023-08-10 20:27:32.890116+00'
        actualRisk: 4
        overrideResidualLikelihood: 'false'
        residualLikelihoodLevel: 3
        overrideResidualLikelihoodBy: ac57e976-69ab-12ab-b991-1284f382c88a
        overrideResidualLikelihoodOn: '2023-08-10 20:27:32.890116+00'
        overrideResidualImpact: 'true'
        residualImpactLevel: 2
        overrideResidualImpactBy: ac57e976-69ab-11ed-b991-1284f382c88d
        overrideResidualImpactOn: '2023-08-10 20:27:32.890116+00'
        actualLikelihood: 8
        actualImpact: 5
        desiredResidualRisk: 16
        actualResidualRisk: 12
        calculatedActualResidualRisk: 15
        customRiskScales:
          likelihood:
            - name: Very Low
              value: 1
              color: '#EDF9F2'
            - name: Low
              value: 2
              color: '#91D4BC'
            - name: Moderate
              value: 5
              color: '#FFB75D'
            - name: High
              value: 8
              color: '#FF8C00'
            - name: Very High
              value: 10
              color: '#C2533B'
          impact:
            - name: Very Low
              value: 1
              color: '#EDF9F2'
            - name: Low
              value: 2
              color: '#91D4BC'
            - name: Moderate
              value: 5
              color: '#FFB75D'
            - name: High
              value: 8
              color: '#FF8C00'
            - name: Very High
              value: 10
              color: '#C2533B'
          inherentRisk:
            - name: Very Low
              value: 1
              color: '#EDF9F2'
              inherentRiskThreshold: 1
            - name: Low
              value: 2
              color: '#91D4BC'
              inherentRiskThreshold: 10
            - name: Moderate
              value: 5
              color: '#FFB75D'
              inherentRiskThreshold: 40
            - name: High
              value: 8
              color: '#FF8C00'
              inherentRiskThreshold: 64
            - name: Very High
              value: 10
              color: '#C2533B'
              inherentRiskThreshold: 100
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            fieldName: Sponsor
            fieldType: text
            textValue: John Smith
        status: active
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: '2023-09-12T18:26:10.005365Z'
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedOn: '2023-09-12T18:26:10.005365Z'
        permissions: []
    RiskFilter:
      type: object
      properties:
        riskIds:
          type: array
          description: List of unique identifiers for risks to return
          items:
            type: string
        modifiedAfter:
          type: string
          format: date-time
          description: Return only risks modified after this date (ISO-8601 format)
        status:
          $ref: '#/components/schemas/ObjectStatus'
        riskStage:
          $ref: '#/components/schemas/RiskStage'
      example:
        riskIds:
          - 23b806db-bad2-4f7a-b8d1-ac1177909992
          - 23b402db-bad2-4f7a-b8d1-ac1177909992
        modifiedAfter: '2020-12-17T20:00:00Z'
        status: active
        riskStage: operating
    RiskPost:
      type: object
      properties:
        riskRegisterId:
          type: string
          description: >-
            The unique identifier for the risk register which the risk will
            belong to. If the intake risk register is provided, the risk will be
            created as a proposed risk.
        riskIdentifier:
          type: string
          description: A human readable unique identifier for the risk
        name:
          type: string
          description: Name of the risk
        description:
          type: string
          description: Description of the risk
        category:
          type: string
          description: Category of the risk
        response:
          $ref: '#/components/schemas/RiskResponse'
        likelihoodLevel:
          type: integer
          description: The inherent likelihood level of the risk. Index notation (0-based)
        likelihoodRationale:
          type: string
          description: The reasoning for the inherent likelihood level of the risk
        impactLevel:
          type: integer
          description: The inherent impact level of the risk. Index notation (0-based)
        impactRationale:
          type: string
          description: The reasoning for the inherent impact level of the risk
        toleranceLevel:
          type: integer
          description: The tolerance level for the risk. Index notation (0-based)
        ownerId:
          type: string
          description: The unique identifier for the user who will be the owner of the risk
        groupId:
          type: string
          description: The unique identifier of the group assigned to the risk
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
      required:
        - riskRegisterId
        - riskIdentifier
        - description
        - ownerId
      example:
        riskRegisterId: 23b806fb-bad2-4f7a-b8d1-ac1177909992
        riskIdentifier: RA-5
        name: Gas Risk
        description: Risks of gas and electricity
        category: Controls Program - Customer Operations
        response: accept
        likelihoodLevel: 1
        likelihoodRationale: security
        impactLevel: 2
        impactRationale: cyber
        toleranceLevel: 0
        groupId: 12ab806f-bad2-4f7a-b8d1-ac117790999a
        ownerId: 23b806db-bad2-4f7a-b8d1-ac117790999b
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            textValue: Antonio Moreno
    RiskPatch:
      type: object
      properties:
        riskIdentifier:
          type: string
          description: A human readable unique identifier for the risk
        name:
          type: string
          description: Name of the risk
        description:
          type: string
          description: Description of the risk
        category:
          type: string
          description: Category of the risk
        ownerId:
          type: string
          description: The unique identifier for the user who will be the owner of the risk
        groupId:
          type: string
          description: >-
            The unique identifier of the group assigned to the risk. If set,
            clearGroupId must not be set
        clearGroupId:
          type: boolean
          description: >-
            Clears the group Unique identifier if `true`. If set, groupId must
            not be set
        response:
          $ref: '#/components/schemas/RiskResponse'
        likelihoodLevel:
          type: integer
          description: The inherent likelihood level of the risk. Index notation (0-based)
        likelihoodRationale:
          type: string
          description: The reasoning for the inherent likelihood level of the risk
        impactLevel:
          type: integer
          description: The inherent impact level of the risk. Index notation (0-based)
        impactRationale:
          type: string
          description: The reasoning for the inherent impact level of the risk
        toleranceLevel:
          type: integer
          description: The tolerance level for the risk. Index notation (0-based)
        clearCategory:
          type: boolean
          description: Clears the category if 'true'. If set, category must not be set
        clearLikelihoodLevel:
          type: boolean
          description: >-
            Clears the likelihood level if 'true'. If set, likelihoodLevel must
            not be set
        clearImpactLevel:
          type: boolean
          description: >-
            Clears the impact level if 'true'. If set, impactLevel must not be
            set
        clearToleranceLevel:
          type: boolean
          description: >-
            Clears the tolerance level if 'true'. If set, toleranceLevel must
            not be set
        status:
          $ref: '#/components/schemas/ObjectStatus'
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldObjectValuePatch'
      example:
        riskIdentifier: RA-5
        name: Gas Risk
        description: Risks of gas and electricity
        category: Controls Program - Customer Operations
        response: accept
        ownerId: 23b806db-bad2-4f7a-b8d1-ac117790999b
        status: archived
        customFields:
          - fieldId: ceb912ab-519b-11ee-a644-522476618ae8
            textValue: Antonio Moreno
    RiskCollection:
      type: array
      items:
        $ref: '#/components/schemas/Risk'
    RiskResponse:
      type: string
      description: The response to the risk
      enum:
        - mitigate
        - accept
        - transfer
        - avoid
        - notSet
    CustomFieldObjectValue:
      type: array
      items:
        type: object
        properties:
          fieldId:
            type: string
            description: Unique identifier for the custom field
          fieldName:
            type: string
            description: Name of the custom field
          fieldType:
            type: string
            description: Type of field
            enum:
              - text
              - number
              - date
              - user
              - textSingleSelect
              - textMultiSelect
          numberFormat:
            type: string
            description: Format if the field type is `number`
            enum:
              - decimal
              - percentage
          textValue:
            type: string
            description: Value if the field type is `text`
          numberValue:
            type: number
            description: Value if the field type is `number`
          dateValue:
            type: string
            description: Value if the field type is `date`
          userValue:
            type: string
            description: Value if the field type is `user`
          selection:
            type: string
            description: Value for `textSingleSelect`
          selections:
            type: array
            description: List of values for `textMultiSelect`
            items:
              type: string
    CustomFieldObjectValuePatch:
      type: object
      properties:
        fieldId:
          type: string
          description: Unique identifier for the custom field
        textValue:
          type: string
          description: Value if the field type is `text`
        numberValue:
          type: number
          description: Value if the field type is `number`
        dateValue:
          type: string
          description: Value if the field type is `date`
        userValue:
          type: string
          description: Value if the field type is `user`
        selections:
          type: array
          description: List of values for `textMultiSelect`
          items:
            type: string
    ObjectStatus:
      type: string
      description: The status of the object
      enum:
        - active
        - archived
    CustomRiskScales:
      type: object
      description: Custom risk scales defined for the risk register the risk belongs to
      properties:
        likelihood:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the likelihood level
              value:
                type: integer
                description: Value of the likelihood level
              color:
                type: string
                description: Color associated with the likelihood level
        impact:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the impact level
              value:
                type: integer
                description: Value of the impact level
              color:
                type: string
                description: Color associated with the impact level
        inherentRisk:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the inherent risk level
              value:
                type: integer
                description: Value of the inherent risk level
              color:
                type: string
                description: Color associated with the inherent risk level
              inherentRiskThreshold:
                type: integer
                description: Threshold value for the inherent risk level
      example:
        likelihood:
          - name: Very Low
            value: 1
            color: '#EDF9F2'
          - name: Low
            value: 2
            color: '#91D4BC'
          - name: Moderate
            value: 5
            color: '#FFB75D'
          - name: High
            value: 8
            color: '#FF8C00'
          - name: Very High
            value: 10
            color: '#C2533B'
        impact:
          - name: Very Low
            value: 1
            color: '#EDF9F2'
          - name: Low
            value: 2
            color: '#91D4BC'
          - name: Moderate
            value: 5
            color: '#FFB75D'
          - name: High
            value: 8
            color: '#FF8C00'
          - name: Very High
            value: 10
            color: '#C2533B'
        inherentRisk:
          - name: Very Low
            value: 1
            color: '#EDF9F2'
            inherentRiskThreshold: 1
          - name: Low
            value: 2
            color: '#91D4BC'
            inherentRiskThreshold: 10
          - name: Moderate
            value: 5
            color: '#FFB75D'
            inherentRiskThreshold: 40
          - name: High
            value: 8
            color: '#FF8C00'
            inherentRiskThreshold: 64
          - name: Very High
            value: 10
            color: '#C2533B'
            inherentRiskThreshold: 100
    RiskStage:
      type: string
      description: The current stage of the risk
      enum:
        - proposed
        - evaluating
        - approved
        - operating
