# Get the loaded tax knowledge

> The knowledge.state.get operation: GET /api/v1/tax/knowledge in the REST API and the knowledge_state_get tool in the MCP server.

Returns which version of the Jurisdiction Knowledge Base the platform uses: the git `commit` it was compiled
from, when it was loaded (`loadedAt`, `loadedBy`) and what that load changed (`lastLoad`), with counts of the
current records per collection and per status. Every change to tax rules is a reviewed commit; the
`knowledge_sync` job loads it after the next deploy. Before anything is loaded, `loaded` is false.

Tax knowledge is shared by every organization and read-only (spec §41.2).

## At a glance

- **REST:** `GET /api/v1/tax/knowledge`
- **MCP tool:** `knowledge_state_get`
- **Operation ID:** `knowledge.state.get`
- **Scope:** Platform
- **Permission:** `tax_knowledge:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `tax_knowledge:read` scope
- **Since:** M3

## Request

### Query parameters

This operation takes no query parameters.

## Response

`200 OK` with a JSON object:

| Field                       | Type                                   | Description |
| --------------------------- | -------------------------------------- | ----------- |
| `object`                    | `"knowledge_state"`                    |             |
| `loaded`                    | boolean                                |             |
| `root`                      | one of `knowledge`, `fixtures` or null |             |
| `commit`                    | string or null                         |             |
| `previousCommit`            | string or null                         |             |
| `loadedAt`                  | date-time or null                      |             |
| `loadedBy`                  | string or null                         |             |
| `counts`                    | object                                 |             |
| `counts.jurisdictions`      | integer (at least 0)                   |             |
| `counts.rates`              | integer (at least 0)                   |             |
| `counts.regimes`            | integer (at least 0)                   |             |
| `counts.filingSpecs`        | integer (at least 0)                   |             |
| `counts.invoicingRules`     | integer (at least 0)                   |             |
| `counts.einvoicingMandates` | integer (at least 0)                   |             |
| `counts.playbooks`          | integer (at least 0)                   |             |
| `counts.sources`            | integer (at least 0)                   |             |
| `counts.territories`        | integer (at least 0)                   |             |
| `statuses`                  | object                                 |             |
| `statuses.total`            | integer (at least 0)                   |             |
| `statuses.researched`       | integer (at least 0)                   |             |
| `statuses.cross_checked`    | integer (at least 0)                   |             |
| `statuses.reviewed`         | integer (at least 0)                   |             |
| `statuses.verified`         | integer (at least 0)                   |             |
| `statuses.retired`          | integer (at least 0)                   |             |
| `fixtures`                  | integer (at least 0)                   |             |
| `lastLoad`                  | object                                 |             |

## Examples

### The knowledge base loaded after a deploy

```http
GET /api/v1/tax/knowledge
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "knowledge_state",
  "loaded": true,
  "root": "knowledge",
  "commit": "1c14b2ec912aca347dd518b2044096f3b5d8eef1",
  "previousCommit": "0b2f4c1e7a9d3b5f8e6c2a4d1f3b5e7c9a1d3f5b",
  "loadedAt": "2026-10-13T03:15:00.000Z",
  "loadedBy": "system:knowledge_sync",
  "counts": {
    "jurisdictions": 82,
    "rates": 394,
    "regimes": 55,
    "filingSpecs": 6,
    "invoicingRules": 2,
    "einvoicingMandates": 8,
    "playbooks": 14,
    "sources": 772,
    "territories": 11
  },
  "statuses": {
    "total": 572,
    "researched": 131,
    "cross_checked": 380,
    "reviewed": 61,
    "verified": 0,
    "retired": 0
  },
  "fixtures": 0,
  "lastLoad": {
    "tax_rates": {
      "added": 2,
      "changed": 1,
      "retired": 0,
      "unchanged": 391
    }
  }
}
```

## Errors

| Code                                                                                   | HTTP status | When                                       | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | Your credentials can't read tax knowledge. | 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): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`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).