# List knowledge review items

> The knowledge.review_items.list operation: GET /api/v1/tax/knowledge/review_items in the REST API and the knowledge_review_items_list tool in the MCP server.

Lists the knowledge review queue, newest first: work on the Jurisdiction Knowledge Base to track, such as
records to promote, changed sources, research diffs, open questions and the research the
`knowledge_schedule` job found due (with a Claude Code prompt). Tracking only: every change to the
knowledge base is a reviewed commit; resolving an item records that commit or pull request.

Filter by `status` and `kind` (one or several each), `jurisdictionId` or `assignee` (a user ID). Paginate
with `limit` (1–100, default 10) and `starting_after` (the previous `next_cursor`). `counts` has the number
of items per status in the whole queue. Platform staff only.

## At a glance

- **REST:** `GET /api/v1/tax/knowledge/review_items`
- **MCP tool:** `knowledge_review_items_list`
- **Operation ID:** `knowledge.review_items.list`
- **Scope:** Platform
- **Permission:** `tax_knowledge:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** API key with the `tax_knowledge:read` scope
- **Since:** M3

## Request

### Query parameters

| Field            | Type                                                                                                                                                                    | Required | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- |
| `status`         | one of `open`, `resolved`, `dismissed` or array of one of `open`, `resolved`, `dismissed`                                                                               | No       |             |
| `kind`           | one of `status_promotion`, `source_changed`, `research_diff`, `open_question` or array of one of `status_promotion`, `source_changed`, `research_diff`, `open_question` | No       |             |
| `jurisdictionId` | string                                                                                                                                                                  | No       |             |
| `assignee`       | `usr_…` ID                                                                                                                                                              | No       |             |
| `limit`          | integer (1 to 100)                                                                                                                                                      | No       |             |
| `starting_after` | `kri_…` ID                                                                                                                                                              | No       |             |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

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

## Examples

### The open queue

```http
GET /api/v1/tax/knowledge/review_items?status=open
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "kri_01m4ttwd3veh9apbewxheq5xhe",
      "object": "knowledge_review_item",
      "kind": "research_diff",
      "status": "open",
      "jurisdictionId": null,
      "recordRef": "waves.yaml#tier1-quarterly@2026-10-01",
      "title": "Recurring wave tier1-quarterly is due (occurrence 2026-10-01)",
      "proposed": "31 jurisdictions in scope. In scope: AT, BE, BG, CH, CY, …",
      "evidenceUrl": null,
      "detectedBy": "research_wave",
      "assignee": null,
      "resolvedByCommit": null,
      "prUrl": null,
      "note": null,
      "prompt": "Run research wave `tier1-quarterly` per spec §42.6 (occurrence 2026-10-01). `pnpm knowledge:wave plan tier1-quarterly --today 2026-10-13` lists its runs and prompts; the wave report goes to data/tax/knowledge/reports/tier1-quarterly-2026-10-01.md.",
      "wave": {
        "id": "tier1-quarterly",
        "occurrence": "2026-10-01"
      },
      "records": [],
      "createdBy": {
        "type": "system",
        "id": "knowledge_schedule"
      },
      "closedBy": null,
      "closedAt": null,
      "createdAt": "2026-10-13T04:00:00.000Z",
      "updatedAt": "2026-10-13T04:00:00.000Z"
    },
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "counts": {
    "open": 2,
    "resolved": 14,
    "dismissed": 3
  }
}
```

### Items assigned to one person

```http
GET /api/v1/tax/knowledge/review_items?assignee=usr_01m4ttwd3veh9apbewxheq5xhf&status=open
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "counts": {
    "open": 2,
    "resolved": 14,
    "dismissed": 3
  }
}
```

## Errors

| Code                                                                                   | HTTP status | When                                  | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | ------------------------------------- | ------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | A filter or the page size is invalid. | 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 platform staff.            | 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), [`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), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).