# Update a knowledge review item

> The knowledge.review_items.update operation: PATCH /api/v1/tax/knowledge/review_items/{id} in the REST API and the knowledge_review_items_update tool in the MCP server.

Changes an item of the knowledge review queue:

- **Assign** an open item to platform staff (`assignee`: a user ID), or unassign it (`assignee: null`).
- **Resolve** an open item (`status: resolved`) with the commit (`resolvedByCommit`) or pull request
  (`prUrl`) that changed the knowledge base, and an optional `note`.
- **Dismiss** an open item that needs no change (`status: dismissed`) with a `note` saying why.
- **Reopen** a resolved or dismissed item (`status: open`).

Tracking only: resolving changes no tax rule; the commit does, once it is merged and loaded. Platform tax
admins only.

## At a glance

- **REST:** `PATCH /api/v1/tax/knowledge/review_items/{id}`
- **MCP tool:** `knowledge_review_items_update`
- **Operation ID:** `knowledge.review_items.update`
- **Scope:** Platform
- **Permission:** `tax_knowledge:admin`
- **Risk tier:** `write`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` optional
- **Modes:** Test and live
- **Authentication:** API key with the `tax_knowledge:admin` scope
- **Since:** M3

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `kri_…` ID |             |

### Body

A JSON object (`Content-Type: application/json`):

| Field              | Type                                   | Required | Description |
| ------------------ | -------------------------------------- | -------- | ----------- |
| `status`           | one of `open`, `resolved`, `dismissed` | No       |             |
| `assignee`         | `usr_…` ID or null                     | No       |             |
| `resolvedByCommit` | string                                 | No       |             |
| `prUrl`            | string                                 | No       |             |
| `note`             | string                                 | No       |             |

## Response

`200 OK` with a JSON object:

| Field                    | Type                                                                          | Description |
| ------------------------ | ----------------------------------------------------------------------------- | ----------- |
| `id`                     | `kri_…` ID                                                                    |             |
| `object`                 | `"knowledge_review_item"`                                                     |             |
| `kind`                   | one of `status_promotion`, `source_changed`, `research_diff`, `open_question` |             |
| `status`                 | one of `open`, `resolved`, `dismissed`                                        |             |
| `jurisdictionId`         | string or null                                                                |             |
| `recordRef`              | string                                                                        |             |
| `title`                  | string                                                                        |             |
| `proposed`               | string or null                                                                |             |
| `evidenceUrl`            | string or null                                                                |             |
| `detectedBy`             | one of `rate_monitor`, `research_wave`, `user`                                |             |
| `assignee`               | object or null                                                                |             |
| `resolvedByCommit`       | string or null                                                                |             |
| `prUrl`                  | string or null                                                                |             |
| `note`                   | string or null                                                                |             |
| `prompt`                 | string or null                                                                |             |
| `wave`                   | object or null                                                                |             |
| `records`                | array of object                                                               |             |
| `records[].ref`          | string                                                                        |             |
| `records[].nextReviewBy` | string                                                                        |             |
| `records[].status`       | one of `researched`, `cross_checked`, `reviewed`, `verified`, `retired`       |             |
| `createdBy`              | object                                                                        |             |
| `createdBy.type`         | string                                                                        |             |
| `createdBy.id`           | string                                                                        |             |
| `closedBy`               | object or null                                                                |             |
| `closedAt`               | date-time or null                                                             |             |
| `createdAt`              | date-time                                                                     |             |
| `updatedAt`              | date-time                                                                     |             |

## Examples

### Resolve with the pull request that changed the knowledge base

```http
PATCH /api/v1/tax/knowledge/review_items/kri_01m4ttwd3veh9apbewxheq5xhd
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "status": "resolved",
  "resolvedByCommit": "9f3c2e1",
  "prUrl": "https://github.com/ownrecord/ownrecord/pull/412",
  "note": "The amendment didn't pass; added a source."
}
```

Response (`200`):

```json
{
  "id": "kri_01m4ttwd3veh9apbewxheq5xhd",
  "object": "knowledge_review_item",
  "kind": "open_question",
  "status": "resolved",
  "jurisdictionId": "HR",
  "recordRef": "HR/rates.yaml#*:standard@2013-01-01",
  "title": "Confirm whether the 2026 budget changes the standard rate",
  "proposed": "Keep 25% unless the amendment passes; add a dated rate if it does.",
  "evidenceUrl": "https://www.porezna-uprava.hr/vijesti",
  "detectedBy": "user",
  "assignee": {
    "id": "usr_01m4ttwd3veh9apbewxheq5xhf",
    "email": "tax@ownrecord.io"
  },
  "resolvedByCommit": "9f3c2e1",
  "prUrl": "https://github.com/ownrecord/ownrecord/pull/412",
  "note": "The amendment didn't pass; added a source.",
  "prompt": null,
  "wave": null,
  "records": [],
  "createdBy": {
    "type": "user",
    "id": "usr_01m4ttwd3veh9apbewxheq5xhf"
  },
  "closedBy": {
    "type": "user",
    "id": "usr_01m4ttwd3veh9apbewxheq5xhf"
  },
  "closedAt": "2026-10-14T09:30:00.000Z",
  "createdAt": "2026-10-13T04:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}
```

### Unassign

```http
PATCH /api/v1/tax/knowledge/review_items/kri_01m4ttwd3veh9apbewxheq5xhd
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "assignee": null
}
```

Response (`200`):

```json
{
  "id": "kri_01m4ttwd3veh9apbewxheq5xhd",
  "object": "knowledge_review_item",
  "kind": "open_question",
  "status": "open",
  "jurisdictionId": "HR",
  "recordRef": "HR/rates.yaml#*:standard@2013-01-01",
  "title": "Confirm whether the 2026 budget changes the standard rate",
  "proposed": "Keep 25% unless the amendment passes; add a dated rate if it does.",
  "evidenceUrl": "https://www.porezna-uprava.hr/vijesti",
  "detectedBy": "user",
  "assignee": null,
  "resolvedByCommit": null,
  "prUrl": null,
  "note": null,
  "prompt": null,
  "wave": null,
  "records": [],
  "createdBy": {
    "type": "user",
    "id": "usr_01m4ttwd3veh9apbewxheq5xhf"
  },
  "closedBy": null,
  "closedAt": null,
  "createdAt": "2026-10-13T04:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}
```

## Errors

| Code                                                                                                                                 | HTTP status | When                                                                                                                         | What to do                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`knowledge_review_item_transition_invalid`](https://ownrecord.io/docs/reference/errors.md#knowledge_review_item_transition_invalid) | 409         | The item's status doesn't allow it (resolving or dismissing a closed item, assigning a closed one).                          | Read the item (`GET /tax/knowledge/review_items/{id}`): resolve or dismiss an open item, reopen a resolved or dismissed one, and assign only open items. |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)                                               | 400         | Nothing to change, a resolve without commit or PR, a dismiss without a note, or an assignee who isn't active platform staff. | Fix the fields listed in `details.issues` and send the request again.                                                                                    |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)                                             | 404         | No review item has this ID.                                                                                                  | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                                     |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)                                                 | 409         | The item changed at the same time; retry.                                                                                    | Fetch the object again and retry the change.                                                                                                             |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)                                               | 403         | You aren't a platform tax admin.                                                                                             | Ask an organization owner or admin for a role or scope that allows this action.                                                                          |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).