---
title: "Aggregated citation-integrity KPI feed"
method: GET
path: "/api/v1/integrity"
tags: ["Governance"]
---

# Aggregated citation-integrity KPI feed

`GET /api/v1/integrity`

## Request

- Base URL: `https://legal.nexusquantum.legal`
- URL: `https://legal.nexusquantum.legal/api/v1/integrity`
- Auth: HTTP bearer

Aggregated citation-integrity score per sub-key × period — the KPI feed a client's risk committee ingests (Nexus SERVES the data; the client governs). Aggregates `integrity_events`: counts of the 6 CitationStatus values, broken/verified/not_verifiable rates, mean Node B (audit) confidence and `byo_share`. **NEVER** per-request rows nor canonical norm ids.

Ownership (a child key never sees another sub-key's data):
- **child** → its own `api_key_id` only.
- **master** → the whole organization (`organization_id`).
- **solo/legacy** → the caller's `user_id`.

Anti-fingerprinting k-anonymity: buckets below the minimum run count (currently 5, operator-configurable) suppress the fine metrics — `mean_nodo_b_confidence` and all `rates` become null and every `counts` value plus `total` are rounded to the nearest multiple of 5. Suppression is a WITHHELD measurement, not a measured zero: a null rate says the bucket was too small to report, never that nothing was found. Confidence is already stored COARSE (0.05 steps); no cross-tenant jurisdiction breakdown.

## Query parameters

- `from` string, date
- `to` string, date
- `period` 'day' | 'week' | 'month'
- `api_key_id` string, uuid
- `group_by` 'key' | 'key_jurisdiction'

## Response `200`

Aggregated integrity buckets.

- IntegrityResponse
  - `data` IntegrityBucket[], required: Buckets sorted by `runs` descending.
    - `api_key_id` string, uuid, nullable, required: Sub-key the bucket is attributed to.
    - `key_prefix` string, nullable: Prefix of the sub-key (resolved only over owned keys).
    - `jurisdiction` string, nullable: Present only when `group_by=key_jurisdiction`.
    - `period` string, required: Bucket label: `all` (no period), `YYYY-MM-DD` (day; Monday for week) or `YYYY-MM` (month).
    - `counts` object, required: Counts of each CitationStatus in the bucket (rounded to multiples of 5 when suppressed).
      - `verified` integer
      - `mismatch` integer
      - `not_found` integer
      - `derogated` integer
      - `pending` integer
      - `not_verifiable` integer
    - `total` integer, required: Total citations verified in the bucket (rounded to a multiple of 5 when suppressed).
    - `runs` integer, required: Number of verification runs (analyses) in the bucket.
    - `runs_any_broken` integer: Runs with ≥1 verified-broken citation.
    - `runs_verification_error` integer: Runs where verification could not execute (fail-safe).
    - `rates` object, required: Fine rates over `total`; all null when the bucket is k-anon suppressed or `total === 0`.
      - `broken_rate` number, nullable: (mismatch + not_found + derogated) / total.
      - `verified_rate` number, nullable
      - `not_verifiable_rate` number, nullable
    - `mean_nodo_b_confidence` number, nullable: Mean Node B (audit) confidence over runs with a numeric value; null when suppressed or no numeric samples. Stored COARSE (0.05 steps).
    - `byo_share` number, required: Fraction of runs served by a BYO engine (0..1). Not suppressed.
  - `verify_engine_version` string, required
  - `requestId` string

## Other responses

- `400`: VALIDATION_ERROR — invalid `from`/`to` or non-UUID `api_key_id`.
- `401`: INVALID_API_KEY.
- `403`: FORBIDDEN_CHILD_KEY — a child key requested a foreign `api_key_id`.
- `404`: NOT_FOUND — a master requested an `api_key_id` outside its organization (anti-enumeration).
- `429`: RATE_LIMITED — RPM exceeded.

---

[API](https://skmtc.dev/nexusquantum/apis/nexus-legal-api.md) · [All operations](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/revisions/4084d8d4eb0b?raw)