> ## Documentation Index > Fetch the complete documentation index at: https://developer.vanta.com/llms.txt > Use this file to discover all available pages before exploring further. # Update risk scenario > Update a risk scenario. ## OpenAPI ````yaml /reference/manage-vanta.json patch /risk-scenarios/{riskScenarioId} openapi: 3.0.0 info: title: Manage Vanta version: 1.0.0 description: >- The REST API lets customers query and mutate Vanta's data. Use this API to automate bulk actions, query data for custom workflows and dashboards, and bolster your security operations **Note for Vanta Gov (FedRAMP) customers:** Select `Vanta Gov (FedRAMP)` from the server dropdown to issue requests against `https://api.vanta-gov.com`. The OAuth token URL shown below defaults to the commercial host — replace it with `https://api.vanta-gov.com/oauth/token`. termsOfService: https://www.vanta.com/terms license: name: UNLICENSED contact: name: API Support url: https://help.vanta.com/ email: support@vanta.com servers: - url: https://api.vanta.com/v1 description: Vanta (Commercial) - url: https://api.vanta-gov.com/v1 description: Vanta Gov (FedRAMP) security: [] paths: /risk-scenarios/{riskScenarioId}: patch: tags: - Risk Scenarios summary: Update risk scenario description: Update a risk scenario. operationId: UpdateRiskScenario parameters: - in: path name: riskScenarioId required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRiskScenarioInput' responses: '200': description: Ok content: application/json: schema: $ref: '#/components/schemas/RiskScenario' examples: Example 1: value: riskId: assets-not-identified-and-protected description: >- Assets are not identified and protected according to company requirements. detailedDescription: null isSensitive: false likelihood: 4 impact: 4 residualLikelihood: 2 residualImpact: 1 categories: - Access control ciaCategories: - Confidentiality treatment: Avoid owner: null note: null riskRegister: Default customFields: [] isArchived: false reviewStatus: DRAFT requiredApprovers: [] type: Risk Scenario identificationDate: '2024-03-07T18:46:05.944Z' scoreBreakdown: - id: inherent-risk kind: SCORE name: Inherent risk score: 16 status: null scoreLabel: High parentId: null - id: impact kind: DIMENSION name: Impact score: 4 status: SCORED scoreLabel: High parentId: inherent-risk - id: likelihood kind: DIMENSION name: Likelihood score: 4 status: SCORED scoreLabel: High parentId: inherent-risk security: - bearerAuth: [] components: schemas: UpdateRiskScenarioInput: properties: description: type: string description: >- This describes an actual or potential risk to your organization's people, processes, technology, data, and facilities. Document actual issues or likely scenarios based on your specific environment or a potential vulnerability. detailedDescription: type: string description: >- Optional long-form description providing extended context for the risk scenario. Maximum 10000 characters. isSensitive: type: boolean description: >- If set to true this risk can only be seen by its owner or users with Admin, RiskSensitiveManage or RiskSensitiveView permissions. deprecated: true likelihood: type: integer format: int32 description: >- Represents the probability of an incident occurring due to this risk or vulnerability, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater likelihood. The range can be customized in the Risk Management settings. impact: type: integer format: int32 description: >- Represents the potential severity of harm to your organization’s operations if this risk is exploited, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater impact. The range can be customized in the Risk Management settings. residualLikelihood: type: integer format: int32 description: >- Represents the adjusted probability of this risk being exploited or affecting operations after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings. residualImpact: type: integer format: int32 description: >- Represents the adjusted severity of harm to your organization’s operations if this risk is exploited after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings. categories: items: type: string type: array description: >- The list of categories this risk scenario belongs to. Each element in the list will become a new custom category if it doesn't match an existing one. You can reference the current category options in the Risk Management settings and/or enter new values. ciaCategories: items: $ref: '#/components/schemas/CIA' type: array description: >- Enter a list of the following for the type of risk documented: - Confidentiality: Risk to data stores, customer/sensitive information, etc. - Integrity: Risk to accuracy or integrity of system settings and/or data - Availability: Risk to normal service operations and critical system functionality treatment: $ref: '#/components/schemas/Treatment' description: >- Indicate how your leadership team wants to address an identified risk. Please note: not all risks need to be addressed immediately (or at all). Your Risk Treatment decision will depend on multiple factors, such as your organization's risk tolerance and the value of the asset that the risk is associated with. The options are: - Mitigate: Identify controls to put in place or tasks to be done that will reduce the risk score. - Transfer: Move risk outside of your organization's set of responsibilities e.g. get cyber liability insurance. - Avoid: Stop doing the activity which is causing the risk to your organization and its assets. - Accept: Decide to live with the risk and take no further actions. - Accept: decide to live with the risk; this may be because it is highly unlikely, has a low financial or operational impact, or the cost and effort to treat the risk far exceeds the value of the asset owner: type: string nullable: true description: >- The person responsible for tracking and mitigating this risk scenario. This should be the email address of a valid Vanta user. note: type: string description: >- Additional context about the risk scenario and why it has specific impact and likelihood scores. riskRegister: type: string description: Name of the risk register to associate with this scenario. customFields: items: $ref: '#/components/schemas/CustomAttribute' type: array description: >- The list of custom fields. You can reference custom fields in the Risk Management settings and/or create new one. The format is: - {label: "field-name", value: "string-representation"} for text, date, number and currency fields - {label: "field-name", value: ["option1", "option2"]} for picklist fields type: $ref: '#/components/schemas/RiskScenarioType' description: >- Changing the risk scenario type (`"Risk Scenario"` vs. `"Enterprise Risk"`) is not supported via update. Requests that include this field will be rejected. To change a risk's type, create a new scenario with the desired type and archive the old one. identificationDate: type: string format: date-time description: >- The date this risk was identified. Matches the "Identified Date" field in the Vanta UI. Omitting the field leaves the existing value unchanged. type: object additionalProperties: false RiskScenario: properties: riskId: type: string description: >- The unique ID of the risk specified by the user. Used to reference and update existing risks. description: type: string description: >- This describes an actual or potential risk to your organization's people, processes, technology, data, and facilities. Document actual issues or likely scenarios based on your specific environment or a potential vulnerability. Naming note: in the UI, `description` is labelled "Title" and `detailedDescription` is labelled "Description". The field names are preserved for backwards compatibility with the public REST API and existing data. detailedDescription: type: string nullable: true description: >- Optional long-form description providing extended context for the risk scenario. Maximum 10000 characters. Naming note: in the UI, `description` is labelled "Title" and `detailedDescription` is labelled "Description". The field names are preserved for backwards compatibility with the public REST API and existing data. isSensitive: type: boolean nullable: true description: >- If set to true this risk can only be seen by its owner or users with Admin, RiskSensitiveManage or RiskSensitiveView permissions. deprecated: true likelihood: type: integer format: int32 nullable: true description: >- Represents the probability of an incident occurring due to this risk or vulnerability, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater likelihood. The range can be customized in the Risk Management settings. A value of `null` indicates that no score has been assigned. impact: type: integer format: int32 nullable: true description: >- Represents the potential severity of harm to your organization’s operations if this risk is exploited, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater impact. The range can be customized in the Risk Management settings. A value of `null` indicates that no score has been assigned. residualLikelihood: type: integer format: int32 nullable: true description: >- Represents the adjusted probability of this risk being exploited or affecting operations after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings. A value of `null` indicates that no score has been assigned. residualImpact: type: integer format: int32 nullable: true description: >- Represents the adjusted severity of harm to your organization’s operations if this risk is exploited after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings. A value of `null` indicates that no score has been assigned. categories: items: type: string type: array description: The list of categories this risk scenario belongs to. ciaCategories: items: $ref: '#/components/schemas/CIA' type: array description: >- A list of the following for the type of risk documented: - Confidentiality: Risk to data stores, customer/sensitive information, etc. - Integrity: Risk to accuracy or integrity of system settings and/or data - Availability: Risk to normal service operations and critical system functionality treatment: allOf: - $ref: '#/components/schemas/Treatment' nullable: true description: >- Indicate how your leadership team wants to address an identified risk. Please note: not all risks need to be addressed immediately (or at all). Your Risk Treatment decision will depend on multiple factors, such as your organization's risk tolerance and the value of the asset that the risk is associated with. The options are: - Mitigate: Identify controls to put in place or tasks to be done that will reduce the risk score. - Transfer: Move risk outside of your organization's set of responsibilities e.g. get cyber liability insurance. - Avoid: Stop doing the activity which is causing the risk to your organization and its assets. - Accept: Decide to live with the risk and take no further actions. - Accept: decide to live with the risk; this may be because it is highly unlikely, has a low financial or operational impact, or the cost and effort to treat the risk far exceeds the value of the asset owner: type: string nullable: true description: >- The email of the person responsible for tracking and mitigating this risk scenario. note: type: string nullable: true description: >- Additional context about the risk scenario and why it has specific impact and likelihood scores. riskRegister: type: string nullable: true description: Name of the risk register associated with this scenario. customFields: items: $ref: '#/components/schemas/CustomAttribute' type: array description: >- The list of custom fields. You can reference existing custom fields in the Risk Management settings and/or create new ones. The format is: - {label: "field-name", value: "string-representation"} for text, date, number and currency fields - {label: "field-name", value: ["option1", "option2"]} for picklist fields isArchived: type: boolean description: Whether this scenario is archived. reviewStatus: $ref: '#/components/schemas/ReviewStatus' description: The current review status of this risk scenario requiredApprovers: items: type: string type: array description: The list of required approvers for this risk scenario. type: $ref: '#/components/schemas/RiskScenarioType' description: |- The type of risk scenario. - "Risk Scenario": Standard risk scenario - "Enterprise Risk": Enterprise-level risk identificationDate: type: string format: date-time description: >- The date this risk was identified. Matches the "Identified Date" field in the Vanta UI. Set by the customer when a risk is created; defaults to the scenario's creation time when not explicitly provided. scoreBreakdown: items: $ref: '#/components/schemas/ScoreBreakdownEntry' type: array nullable: true description: >- Overall inherent score, dimensions, and nested factors, ordered parents before children and linked by `parentId`. `null` when Flexible Risk Scoring is off or the scenario has no score or matching config. Closed beta. required: - riskId - description - isSensitive - likelihood - impact - residualLikelihood - residualImpact - categories - ciaCategories - treatment - owner - note - riskRegister - customFields - isArchived - reviewStatus - requiredApprovers - type - identificationDate - scoreBreakdown type: object additionalProperties: false CIA: type: string enum: - Confidentiality - Integrity - Availability Treatment: type: string enum: - Mitigate - Transfer - Avoid - Accept CustomAttribute: properties: label: type: string value: anyOf: - type: string - items: type: string type: array required: - label - value type: object additionalProperties: false RiskScenarioType: type: string enum: - Risk Scenario - Enterprise Risk ReviewStatus: type: string enum: - APPROVED - DRAFT - NOT_REVIEWED - AWAITING_SUBMISSION - PENDING_APPROVAL - REQUESTED_CHANGES ScoreBreakdownEntry: description: >- One node in the inherent risk scoring tree. Entries are ordered parents before children, with `parentId` linking each child to its parent. properties: id: type: string description: >- Config node ID, unique within this breakdown. IDs can change when the scoring config is restructured; re-read the breakdown instead of storing them long-term. kind: $ref: '#/components/schemas/ScoreBreakdownEntryKind' description: Whether this entry is the overall score, a dimension, or a factor. name: type: string description: Display name of this node, from the scoring config. score: type: number format: double nullable: true description: >- Entered or calculated value, which may be fractional. `null` when unscored, not applicable, or no aggregate value is available; see `status` for leaf nodes. status: allOf: - $ref: '#/components/schemas/ScoreBreakdownEntryStatus' nullable: true description: >- Scoring status for a directly scored node. `null` for aggregates; read their children's statuses instead. scoreLabel: type: string nullable: true description: >- Matching option label for a directly scored node, or the register's range-band label for the overall score. `null` when no label applies, including non-root aggregates and overall scores on registers using matrix-based severity. parentId: type: string nullable: true description: Parent entry's ID, or `null` for the overall score. required: - id - kind - name - score - status - scoreLabel - parentId type: object additionalProperties: false ScoreBreakdownEntryKind: type: string enum: - SCORE - DIMENSION - FACTOR description: >- `SCORE` is the root, `DIMENSION` is a direct child, and `FACTOR` is any deeper node. ScoreBreakdownEntryStatus: type: string enum: - SCORED - MISSING - NOT_APPLICABLE description: |- `SCORED` has an entered value; `MISSING` is unscored; `NOT_APPLICABLE` is excluded from its parent's calculation. securitySchemes: bearerAuth: type: http scheme: bearer ```` ## Related topics - [Create and update risk scenarios](/docs/guides/create-risk-scenarios.md) - [Create risk scenario](/api-reference/risk-scenarios/create-risk-scenario.md) - [List risk scenarios](/api-reference/risk-scenarios/list-risk-scenarios.md) - [Change a risk scenario control's controlType](/api-reference/risk-scenarios/change-a-risk-scenario-controls-controltype.md) - [Get risk scenario by ID](/api-reference/risk-scenarios/get-risk-scenario-by-id.md)