# Open a knowledge review item

> The knowledge.review_items.create operation: POST /api/v1/tax/knowledge/review_items in the REST API and the knowledge_review_items_create tool in the MCP server.

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 | Description |
| ---------------- | ----------------------------------------------------------------------------- | -------- | ----------- |
| `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`](https://ownrecord.io/docs/reference/errors.md#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`](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), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`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).