API

Governed Interface Draft

The canonical public v1 draft is POST /v1/govern/evaluate. Until the control plane is launched, this page is a draft contract and not a production availability claim.

Stability Labels

Label	Meaning
Draft	Contract may change before launch.
Preview	Usable for testing with migration risk.
Stable	Versioned and covered by compatibility policy.

Request Lifecycle

request
  -> authenticate
  -> validate schema
  -> apply review constraints
  -> create review record
  -> return verdict, reason, repair notes, and record reference

Draft Endpoints

Endpoint	Status	Purpose
`GET /health`	Draft	Report service readiness.
`POST /v1/govern/evaluate`	Draft	Review a proposed work action and return status, reason, repair notes, and record details.

Canonical Example

{
  "request": {
    "action": "publish_release_note",
    "risk_type": "public_release",
    "evidence_refs": ["release-note-draft"],
    "reviewer": "human-reviewer"
  },
  "response": {
    "status": "hold_for_approval",
    "reason": "public release requires reviewer acceptance",
    "repair_notes": ["attach approval reference before execution"],
    "record_ref": "draft-record-reference"
  }
}

Error Contract

API errors should be typed, explicit, and traceable. Silent failures are not accepted. Each rejected request must include a bounded reason that can be logged and audited.