---
title: "Register Faithfulness Spec"
method: POST
path: "/model/{env}/faithfulness-spec"
---

# Register Faithfulness Spec

`POST /model/{env}/faithfulness-spec`

## Request

- Base URL: `https://api-docs.session-exchange.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.session-exchange.com/model/{env}/faithfulness-spec`
- Auth: none declared

Register a GOVERNED FaithfulnessSpec (1a): it names the INDEPENDENT ground-
truth source + the passing threshold the collector uses to RECOMPUTE the reading.
Admin-only, immutable, versioned — the loop authors the schema, never the thing
that grades it. The threshold can't be below the governed floor
(faithfulness_min_threshold), which kills the 'threshold=0.0 clears it' hole.

## Path parameters

- `env` string, required

## Request body

- FaithfulnessSpecRequest: A GOVERNED faithfulness spec (Phase 1, 1a): declares HOW the collector recomputes a scope's held-out faithfulness — the predicted field (from a schema entity type) vs. an INDEPENDENT ground-truth projection — plus the passing threshold. Admin-only; the loop reads it, never authors it. predicted: {"entity_type": "<schema entity>", "field": "<projected field>"} ground_truth: {"event_types": [...], "key": "<dotted>", "value_path": "<dotted>"} compare: "exact" | {"numeric_tol": <float>} (default exact)
  - `scope` string
  - `predicted` object, required
  - `ground_truth` object, required
  - `threshold` number, required
  - `test_frac` number
  - `compare` unknown

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/session-exchange/apis/a4sx.md) · [All operations](https://skmtc.dev/session-exchange/apis/a4sx/llms.txt) · [OpenAPI document](https://skmtc.dev/session-exchange/apis/a4sx/revisions/abaefc33dfc7?raw)