Update a knowledge review item

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
`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`	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`	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`	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`	409	The item changed at the same time; retry.	Fetch the object again and retry the change.
`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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Resolve with the pull request that changed the knowledge base#

Unassign#

Errors#