--- title: "Get Requirement Examples" method: GET path: "/marketing/requirement-coverage/requirements/{requirement_id}/examples" tags: ["marketing-requirement-coverage"] --- # Get Requirement Examples `GET /marketing/requirement-coverage/requirements/{requirement_id}/examples` The most recent times this requirement met collateral, with the finding and the decision. What the tuning surfaces read instead of guessing from counts. A rate says a rule is wrong; these say *how* — the passage it fired on, the reviewer's reason, and the note they left, which is the only place anybody writes down what was actually wrong with the wording. **The unit is a firing, not a finding.** One check can produce several risks — two passages, two findings — so a limit counted in rows would answer "the last five times this fired" with five findings from one asset. The checks are chosen first, with a real `LIMIT` per requested verdict, and their findings fetched afterwards; `findings` on each example says how many that firing produced so nothing is hidden by showing one. That shape is also what makes `truncated` true. An earlier version read a fixed budget of joined rows and bucketed them in Python, which meant a rule with hundreds of confirmations could starve a request for its three dismissals and answer `truncated: false` — asserting it had shown the whole history of a list it never reached. **`limit` is per requested verdict**, not per response. Asking for five with two verdicts returns up to ten, because the surface needs the last five dismissals *and* the confirmations on screen together: a rewording that loses the dismissals by also losing the confirmations is a regression the wording alone does not show. Said out loud because "limit 5" returning ten is otherwise something a caller discovers. `outcome` is **repeatable, and omitting it means `FAILED`** — "why did this fire" is the question both surfaces open with. Repeatable rather than a single value with a nullable default, because a nullable default has no wire spelling: `outcome=` and `outcome=null` are both enum errors, so "every outcome" would have been unaskable over HTTP and reachable only from Python. A `FAILED` check with no surviving risk is returned as `FIRED_NO_FINDING` rather than dropped. The findings a check produces pass through obsolescence deduplication and, for some companies, a confidence filter, and both drop dicts before anything reaches `document_risks` — so the rule a fire-rate ranking just put first can legitimately have fired with nothing to show. An empty flipper reads as the surface being broken; the answer reads as the answer. ## Path parameters - `requirement_id` string, uuid, required ## Query parameters - `verdict` ProductionRiskVerdict[], nullable - `outcome` RequirementCheckOutcome[], nullable - `limit` integer ## Response `200` Successful Response - RequirementExamples — Examples of one requirement's history, grouped by nothing — the client groups by verdict. `limit` is applied **per requested verdict**, so asking for five with two verdicts returns up to ten rows. That is what the surface needs (the last five dismissals *and* the confirmations, on screen together) and it is stated because "limit 5" returning ten is otherwise something a caller discovers. - `requirement_id` string, uuid, required - `examples` RequirementExample[] - `kind` 'fired' | 'fired_no_finding' | 'not_fired', required — What kind of evidence one example is. `FIRED_NO_FINDING` is the one worth naming. A `FAILED` check can end with no risk at all — the findings it produced pass through obsolescence deduplication and, for some companies, a confidence filter, both of which drop dicts before anything reaches `document_risks`. Without a kind of its own, the rule a `FIRE_RATE` ranking just put first could open an empty flipper, and a reader would read that as the surface being broken rather than as the answer it is. - `outcome` 'passed' | 'failed' | 'not_determined', required — What happened when one requirement met one piece of collateral. Stored rather than derived. "We checked 34 requirements and 3 failed" cannot be reconstructed from the risks alone: a requirement that produced no finding is indistinguishable in `document_risks` from one that was never evaluated, and that difference is the whole feature. **`NOT_DETERMINED` is why the model is asked to answer for every rule** rather than only to report failures. Silence has two meanings — "the collateral satisfies this" and "I cannot tell from what the collateral shows" — and a panel that reads the first from the absence of a finding claims a pass the model never gave. The judging contract therefore makes each rule land in exactly one of these three, and a rule the model omits altogether lands here too. - `run_id` string, uuid, required - `file_id` string, uuid, required - `filename` string, nullable - `document_id` string, uuid, required - `checked_at` string, date-time, required - `revision_id` string, uuid, required - `requirement_text` string, required - `judging_guidance` string, nullable - `matched_trigger_terms` string[] - `findings` integer - `citation` RequirementCitation, required — Where the requirement itself sits in the standards document it came from. A serialized `GroundedSpan` plus the exact version its boxes were measured against. The version is the load-bearing half: the boxes are coordinates in the bytes the decomposition read, so resolving the document any other way draws the highlight in the wrong place on a standard that has since been re-uploaded. - `guideline_file_id` string, uuid, required - `guideline_filename` string, nullable - `guideline_upload_id` string, uuid, nullable - `grounding` object, nullable - `risk` RequirementExampleRisk — The finding one check produced, as a reviewer sees it on the card. A subset of the risk rather than the whole `DocumentRiskResponse`: this is read beside the requirement being edited, so what earns its place is what the wording has to answer for — the claim, the passage, the reviewer's decision and the note they left with it. `source_clause` is deliberately **not** here. It is the machine-readable routing prefix plus the rule, and the rule is already the subject of the page; including it would put a second, staler copy of the wording beside the live one. - `risk_id` string, uuid, required - `short_text` string, required - `explanation` string, required - `remediation` string, nullable - `severity` 'low' | 'medium' | 'high', required - `document_clause` string, nullable - `citations` DocumentRiskCitation[], nullable - `cited_text` string, required - `start_page_number` integer, required - `end_page_number` integer, required - `bounding_boxes` BoundingBox[] - `x0` number, required - `y0` number, required - `x1` number, required - `y1` number, required - `status` 'reject' | 'allow' | 'flag' | 'dismissed' - `dismiss_reason` 'valid_ok' | 'already_met' | 'incorrect' | 'out_of_scope' | 'pre_approved' | 'other' — Why a reviewer dismissed a marketing risk (status=dismissed). - `dismiss_note` string, nullable - `verdict` 'flagged' | 'dismissed_over_flagged' | 'dismissed_accepted' | 'dismissed_other' | 'unreviewed', required — The reviewer's decision on a production risk, derived from its stored columns. `SUPERSEDED` is deliberately **not** a member: obsoletion is a property of the run, not a decision by a reviewer, and a risk can be dismissed and later superseded. Collapsing them would throw away the reviewer's decision — which is the thing this dashboard exists to compare against. It travels as its own boolean. - `actioned_at` string, date-time, nullable - `superseded` boolean - `suppressed` boolean - `truncated` boolean ## Other responses - `422` — Validation Error --- [API](https://skmtc.dev/kobaltlabs/apis/fastapi.md) · [All operations](https://skmtc.dev/kobaltlabs/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kobaltlabs/fastapi/revisions/816d6dca5096/schema)