API reference

Build customer frontends to Blackboard.

Use Blackboard as the single governance backend. Start integrator implementation against the local preview for stable core route shapes, then move to the hosted gateway as each parity endpoint ships.

export BLACKBOARD_BASE_URL="http://127.0.0.1:8097"
python3 ./scripts/if_blackboard_governance_api.py smoke

The preview smoke generates its own loopback token. Hosted `https://api.infrafabric.io/v1` is the target gateway, not a completed full `/v1` service claim.

Local API preview

The integrator pack includes a localhost HTTP preview for the route and payload shapes builders need now. It uses a per-run preview token and writes to a local append-only event store.

export BLACKBOARD_BASE_URL="http://127.0.0.1:8097"
python3 ./scripts/if_blackboard_governance_api.py smoke

Preview route	What it proves
`GET /health`	Preview status and route list.
`OPTIONS /v1/events`	Loopback-scoped, bodyless preflight without wildcard CORS.
`POST /v1/events`	Validated event writes, idempotency check and append-only local event truth.
`GET /v1/tasks/{task_id}/timeline`	Tenant-scoped timeline hydrated from event truth.
`GET /v1/search`	Tenant-scoped search as discovery, not proof authority.
`POST /v1/claim-boundaries/evaluate`	Claim Boundary decision with semantic-correctness non-claim.
`POST /v1/proof-packets`	Schema-valid Proof Packet v1 assembly.

The preview also rejects customer writes over operator transport and blocks cross-tenant plus same-tenant cross-workspace packet confusion. It is not production OAuth, hosted gateway, managed MCP, WebSocket, database isolation or production signing proof.

Feature parity endpoints

Only the local preview routes are currently smoked. The broader registry, risk, approval, regulatory, vendor, incident, review, team, notification and export endpoints are target contracts until their schemas and endpoint smokes exist.

Builder feature	Blackboard API	State truth
Dashboard posture	`GET /v1/governance/dashboard`	Projection hydrated from event truth
AI use registry	`GET\|POST /v1/governance/assets`	`governance.asset.registered`
Risk score	`POST /v1/risk/evaluations`, `GET /v1/governance/assets/{asset_id}/risk`	`risk.evaluated`
Approvals	`GET /v1/approvals`, `POST /v1/approvals/{approval_id}/decision`	`approval.requested`, `approval.decided`
Evidence	`GET /v1/governance/assets/{asset_id}/evidence`, `POST /v1/evidence/sanitize`	`evidence.attached`, `evidence.sanitized`
Regulatory posture	`GET /v1/regulatory/profiles`, `GET /v1/regulatory/posture`, framework `PATCH` routes	`regulatory.posture.updated`
Vendors	`GET /v1/vendors/questions`, `POST /v1/vendors`	`vendor.assessed`
Incidents	`GET\|POST\|PATCH /v1/incidents`	`incident.logged`, `incident.updated`
Periodic reviews	`GET /v1/reviews`, `POST /v1/reviews/{review_id}/complete`	`review.completed`
Team/settings	`GET /v1/team`, invite create/revoke routes	`access.logged`, admin events
Exports	`GET /v1/exports/*`, `POST /v1/proof-packets`	`proof_packet.assembled`, `access.logged`

Capability APIs

These APIs prevent the UI from owning governance logic.

API	Purpose	Claim boundary
`POST /v1/risk/evaluations`	Server-side risk calculation with policy version, input hash and event binding.	Risk route is evidence-backed, not magic certainty.
`POST /v1/claim-boundaries/evaluate`	Classify verified, claimed, inferred, stale, missing, blocked and not-claimed statements.	Semantic correctness is never automatic.
`POST /v1/evidence/sanitize`	Quarantine raw evidence and produce safe projections.	Raw evidence is untrusted until sanitized or reviewer-approved.
`POST /v1/signatures/verify`	Verify hash, signature, hash-chain and receipt binding.	Integrity proof is not semantic proof.

Agent honesty APIs

Use these APIs to make promised governance real. Mechanical checks are enforced by the service; reviewers are assigned when judgment is needed.

API	Purpose
`GET /v1/templates/task-closeout`	Return required closeout fields, evidence checklist, default non-claims and missing-field policy.
`GET /v1/templates/proof-packet`	Return packet assembly requirements, redaction defaults, non-claims and export blockers.
`GET /v1/templates`, `GET /v1/templates/{template_id}`	List/fetch smart templates for search, new task, session bind, evidence attach, checkpoint, risk, approval, regulatory update, access log, packet and closeout.
`POST /v1/templates/validate`	Validate a filled template and return blockers, warnings, reviewer triggers and next required evidence.
`GET /v1/sessions/{session_id}/provenance`	Show user/service account, agent, client app, host, IP class, transport and source harness.
`GET /v1/access-log`	Query who viewed, exported, approved, changed or attempted access.

Managed MCP parity

Agent-facing features use the same capability surface through scoped MCP tools.

{
  "tool": "if.blackboard.risk.evaluate",
  "arguments": {
    "asset_id": "asset_demo",
    "risk_inputs": {
      "data_sensitivity": 3,
      "decision_impact": 3,
      "autonomy": 2,
      "vendor_maturity": 2,
      "prohibited_practice": 0
    }
  }
}

Contract verifier

The preview contract is release-checked against the same Blackboard ensemble boundary: event truth to Proof Desk to Proof Packet v1, signed or hash-bound updates, Claim Boundary Engine, tenant isolation, governed HTTPS API, managed MCP, WebSocket notifications and no customer SSH.

blackboard contracts smoke
blackboard contracts conformance

The target CLI command is shown for integrators. The current preview pack also includes the local verifier script used to generate and validate the published sample event and Proof Packet contracts.

Static examples and smoked preview

The local API preview smoke is executable today. The broader REST and MCP files are target-contract examples for implementers.