Open a knowledge review item

Adds an item to the knowledge review queue: something in the Jurisdiction Knowledge Base to look at, such as a record ready for promotion (status_promotion), a changed source (source_changed), a research diff (research_diff) or an open question or dispute (open_question). Name what it is about in recordRef (a record such as HR/rates.yaml#*:standard@2013-01-01 or HR/regimes/HR_DOMESTIC.yaml, or a source such as HR:S3) and optionally assign it to platform staff. detectedBy defaults to user; items from the rate monitor or a research wave raise a KNOWLEDGE_REVIEW_OPEN alert.

Tracking only: nothing here changes tax rules. The change is a commit in the knowledge base, reviewed as a pull request; resolve the item with that commit or pull request. Platform tax admins only.

At a glance

REST: POST /api/v1/tax/knowledge/review_items
MCP tool: knowledge_review_items_create
Operation ID: knowledge.review_items.create
Scope: Platform
Permission: tax_knowledge:admin
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the tax_knowledge:admin scope
Since: M3

Request

Body

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

Field	Type	Required
`kind`	one of `status_promotion`, `source_changed`, `research_diff`, `open_question`	Yes
`jurisdictionId`	string	No
`recordRef`	string	Yes
`title`	string	Yes
`proposed`	string	No
`evidenceUrl`	string	No
`detectedBy`	one of `rate_monitor`, `research_wave`, `user`	No
`assignee`	`usr_…` ID	No
`prompt`	string	No

Response

201 Created 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

An open question, assigned to a tax admin

HTTP

POST /api/v1/tax/knowledge/review_items
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "kind": "open_question",
  "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",
  "assignee": "usr_01m4ttwd3veh9apbewxheq5xhf"
}

Response (201):

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": {
    "id": "usr_01m4ttwd3veh9apbewxheq5xhf",
    "email": "tax@ownrecord.io"
  },
  "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-13T04:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A field is missing or invalid, or the assignee isn't active platform staff.	Fix the fields listed in `details.issues` and send the request again.
`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, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

An open question, assigned to a tax admin#

Errors#