# v2 API contract and migration notes

The authenticated `GET /api/v2/openapi` endpoint generates OpenAPI from the
registered Spring MVC mappings, actual Jackson request names and validation
annotations. Contract tests compare these routes and DTO constraints, including
`POST /api/v2/knowledge/versions/search`. Tests export
`harness-api/target/generated-api/openapi.v2.json`; do not maintain a handwritten
copy of the specification in source control.

## Authentication and modes

Every `/api/**` request requires an explicit bearer. Demo uses five public
synthetic identities with separate roles and literal Host/Origin boundaries.
Blank demo identity configuration selects those defaults; `[]` disables them.
Pilot accepts verified OIDC JWTs with issuer/audience/tenant/role/scope claims,
rejects demo/static credentials, and returns 410 for authenticated v1 requests.
Use your organization IdP and the deployment configuration described in the
[README](../../README.md); local signed fixtures do not prove IdP acceptance.

## Response and concurrency conventions

- Case/execution endpoints return views; versioned resources return record
  envelopes with `id`, `version` and `data`. Use the generated operation schema.
- Case/execution/audit pages use `cursor`; quality lists use `next_cursor`.
  Preserve opaque cursors unchanged. Audit binds timestamp and event ID.
- Mutations use the documented integer expected version; executions also use
  an Idempotency-Key. A repeated key with changed body returns 409.
- Re-read after a conflict. Do not automatically retry an approval using a
  new version without inspecting the new evidence.
- Async execution returns 202; poll its status to distinguish SUCCESS,
  DEGRADED, FAILED, TIMED_OUT and CANCELLED. Acceptance is not completion.
- Unknown authoritative facts or amounts remain null/absent; candidate values
  and legacy minute counters do not establish a determined decision.

## Important boundaries

Policy and knowledge publication, runtime release, feedback verification,
materials and case review enforce independent identities. Case creators and
decision authors cannot claim or approve their own reviews. Missing legacy
authorship requires fresh analysis. High-risk/manual review needs SUPERVISOR.

Lists use explicit metadata projections, not full documents or runtime bundles.
Use authorized detail reads for rules, knowledge, runtime configuration and
feedback corrections. Runtime visibility includes every embedded knowledge
scope in addition to policy scope. Evaluation visibility also covers samples.

`GET /api/v2/eval/runs/{id}/results` returns paged record envelopes whose data
includes `sample_id`, `execution_status`, `scores` and `baseline_scores`.
Score summaries preserve measurement status, per-dimension pass/precision/recall
and hard-gate failure codes, without raw expected/actual values, evidence orders
or execution bodies. Missing labels remain NOT_MEASURED. V10 repairs existing
result projections; frozen payloads and record versions are unchanged.

Model task configuration cannot override system constraints. Refunds require
explicit verified refundable balance; order amount is not a substitute.
Manual exception amount is a JSON number and remains an advisory proposal.
Case export is POST and records an audit receipt; GET returns 405.

## Errors

400 means request validation failed, 401 missing/invalid identity, 403 denied
action, 404 missing or out-of-scope resource, and 409 stale version/idempotency/
state conflict. Semantic evidence/privacy failures may return 422, capacity
limits 429, and dependency failures 502/503/504. Inspect the structured error
code; never infer a successful decision from HTTP status alone.

## Scope exclusions

Approval remains advisory / NOT_EXECUTED. This implementation has no payment
execution, ledger, payment callback or irreversible retention-deletion route.
FR-14 and actual deletion require a separate project after M2 acceptance.