---
title: "Update Factor Rating"
method: PATCH
path: "/risk-assessment/factor-assessments/{factor_assessment_id}"
tags: ["risk-assessment"]
---

# Update Factor Rating

`PATCH /risk-assessment/factor-assessments/{factor_assessment_id}`

Set or clear the reviewer's manual override.

Setting a value moves `review_state` to `OVERRIDDEN` and stamps the
reviewer; explicitly clearing it (`null`) reverts to the AI's suggestion
and `review_state` back to `PROPOSED` — clearing is "undo the override",
not "approve", so it does not stamp an approval. `reviewer_note` is
independent of the rating and can be set on its own.

## Path parameters

- `factor_assessment_id` string, uuid, required

## Request body

- UpdateFactorRatingRequest — A reviewer setting or clearing their manual override. `manual_inherent_risk_label` distinguishes "not provided" from "explicitly null" via `model_fields_set` (same convention as `UpdateRiskFactorCheckRequest`): omit the field to leave the rating untouched, or pass `null` to clear the override back to the AI suggestion.
  - `manual_inherent_risk_label` string, uuid, nullable
  - `reviewer_note` string, nullable

## Response `200`

Successful Response

- FactorAssessmentSummary — One row of the run overview — no steps, no citations.
  - `factor_assessment_id` string, uuid, required
  - `risk_factor` FactorRef, required
    - `risk_factor_id` string, uuid, nullable, required
    - `slug` string, required
    - `name` string, required
  - `status` 'queued' | 'running' | 'complete' | 'error', required — Lifecycle of one factor's assessment within a run. There is no deferral state: a factor either produces a rating its rationale can defend, or it errors. Missing evidence is narrated in the rationale.
  - `progress_pct` integer, nullable, required
  - `current_activity` string, nullable, required
  - `suggested_rating` RatingOptionView, required — One level of the tenant's INHERENT_RISK_LEVEL scale. The scale is per-tenant and variable length, so the UI renders N cells from this list rather than assuming five. `position` is 1-based and derived from order, not from `order_index`, which may be sparse.
    - `option_id` string, uuid, required
    - `label` string, required
    - `position` integer, required
    - `hex_color` string, nullable, required
  - `manual_rating` RatingOptionView, required — One level of the tenant's INHERENT_RISK_LEVEL scale. The scale is per-tenant and variable length, so the UI renders N cells from this list rather than assuming five. `position` is 1-based and derived from order, not from `order_index`, which may be sparse.
    - `option_id` string, uuid, required
    - `label` string, required
    - `position` integer, required
    - `hex_color` string, nullable, required
  - `effective_rating` RatingOptionView, required — One level of the tenant's INHERENT_RISK_LEVEL scale. The scale is per-tenant and variable length, so the UI renders N cells from this list rather than assuming five. `position` is 1-based and derived from order, not from `order_index`, which may be sparse.
    - `option_id` string, uuid, required
    - `label` string, required
    - `position` integer, required
    - `hex_color` string, nullable, required
  - `review_state` 'proposed' | 'approved' | 'overridden', required — Where a human reviewer stands on the agent's proposed rating. Written by the approval workflow (M5); until then every completed factor sits at PROPOSED, which is what renders the "Kobalt proposed" chip.
  - `reviewer_name` string, nullable, required
  - `reviewed_at` string, date-time, nullable, required
  - `citation_count` integer, required
  - `distinct_document_count` integer, required
  - `step_count` integer, nullable, required
  - `duration_ms` integer, nullable, required
  - `error` string, nullable, required
  - `agent_run_id` string, uuid, nullable, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/kobaltlabs/apis/fastapi.md) · [All operations](https://skmtc.dev/kobaltlabs/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kobaltlabs/fastapi/revisions/3ff4c0bd276b/schema)