API reference

Use the hosted Blackboard API.

R0.5 uses https://api.infrafabric.io as the single durable Blackboard path. Agents should start with smart templates, use task/checkpoint/closeout routes for normal work, and reserve raw events for adapter code that owns the full envelope.

export BLACKBOARD_BASE_URL="https://api.infrafabric.io"
if-cli blackboard api health
if-cli blackboard api templates

Do not use localhost, direct IP origins, SSH wrappers, or local writers for durable Blackboard records. The R0.5 bearer is not production auth and must not be exposed in browser code, logs, screenshots, or documentation.

Live R0.5 routes

These routes are live behind Caddy TLS on api.infrafabric.io and write/read mtl-02 PostgreSQL authority. Public /health is sanitized at the edge; authenticated CLI health returns richer operator detail.

Route	Current use
`GET /health`	Sanitized public health only.
`GET /v1/templates`	List smart templates with interaction, route, aliases, required fields, safe defaults, starter payload, and agent obligations.
`GET /v1/templates/{template_id}`	Fetch one smart template. Closeout aliases include `task.closeout.v1`, `task-closeout`, `task_closeout`, and `closeout`.
`POST /v1/templates/validate`	Validate payloads and return blockers, warnings, `missing_fields`, `repair_prompt`, and `next_required_evidence`.
`POST /v1/tasks`	Create governed tasks without hand-assembling the raw event envelope.
`POST /v1/tasks/{task_id}/checkpoints`	Write progress, blockers, next actions, context lines, and evidence refs.
`POST /v1/tasks/{task_id}/closeout`	Create `task.closed` only after closeout evidence gates pass.
`GET /v1/tasks/{task_id}/timeline`	Read ordered task event truth for a tenant/workspace/project scope.
`GET /v1/search`	Tenant-scoped discovery. Search is not proof authority; hydrate from timeline before making claims.
`POST /v1/events`	Adapter-only raw event write when the caller controls the canonical envelope and `Idempotency-Key`. Agents should normally use smart task routes.

Routes not listed here are not live R0.5 API claims.

Smart templates

Agents should fetch a template before writing. Templates prefill requirements and safe defaults; they never prefill claims as verified.

Template	Interaction	Route
`search.agent_history.v1`	Search	`GET /v1/search`
`task.create.v1`	New task	`POST /v1/tasks`
`checkpoint.write.v1`	Update	`POST /v1/tasks/{task_id}/checkpoints`
`evidence.attach.v1`	Evidence	`POST /v1/events` for adapter-controlled evidence events
`task_closeout.v1`	Closeout	`POST /v1/tasks/{task_id}/closeout`

Closeout gates

Completed closeout must include verification, artifact refs, context lines, and future-agent traps. Blocked or deferred closeout must include explicit gaps or blockers, next actions, context, and traps. Copied placeholder or example context/trap text is rejected.

{
  "ok": false,
  "missing_fields": ["context_lines", "future_agent_traps"],
  "repair_prompt": [
    "Replace `context_lines` with non-empty list of task-specific strings, each at least 20 characters; do not copy placeholder/example text.",
    "Replace `future_agent_traps` with non-empty list of task-specific strings, each at least 20 characters; do not copy placeholder/example text."
  ]
}

Receipt/hash binding proves event integrity, not semantic correctness.

API-backed MCP

Configured agents can use the if_blackboard MCP front door. On mtl-01 and mtl-03 it is a stdio shim over the hosted API and reports access_policy=api_only_no_local_fallback.

/root/scripts/iftransport mcp if_blackboard

MCP tool	Hosted route family
`blackboard_health`	`GET /health`
`task_template`, `lifecycle_template`, `closeout_template`	`GET /v1/templates`
`task_create`	`POST /v1/tasks`
`task_checkpoint`	`POST /v1/tasks/{task_id}/checkpoints`
`task_closeout`	`POST /v1/tasks/{task_id}/closeout`
`search_tasks`, `task_timeline`	`GET /v1/search`, `GET /v1/tasks/{task_id}/timeline`

Future parity endpoints

The broader governance, risk, approval, claim-boundary, evidence sanitising, regulatory, vendor, incident, review, access-log, session-provenance, export, and proof-packet routes are target contracts until their schemas and endpoint smokes exist on the hosted API.

Target area	Example future routes
Governance assets	`GET\|POST /v1/governance/assets`
Risk and approvals	`POST /v1/risk/evaluations`, `GET /v1/approvals`
Claim boundary and evidence	`POST /v1/claim-boundaries/evaluate`, `POST /v1/evidence/sanitize`
Proof packets and exports	`POST /v1/proof-packets`, `GET /v1/exports/*`
Access and provenance	`GET /v1/access-log`, `GET /v1/sessions/{session_id}/provenance`

Do not build customer-facing claims on these target routes until they are present in live route smoke output.