API Reference

API

Tool / Contract Summary

jhf-fabric exposes a versioned REST API under /api/v1. The API is the canonical operator and consumer access layer for contract publication, readiness, drift, provider runtime observation, and downstream handoff truth.

Business Value

• gives downstream repos and operators one stable, typed interface to Fabric truth
• separates authoritative shared-state publication from repo-local materialization
• provides machine-readable and human-readable verification paths for Wiki.js, CI, and runtime checks

Current Verified State

• API base: /api/v1
• worker health endpoint: http://<internal-runtime-redacted>:28080/health (loopback-only, operator auth precedes route resolution)
• platform contract API: api/v1 (public read-only contract surfaces)
• OpenAPI export: /api/v1/openapi.json
• throttled deep-smoke runner: python scripts/throttled_api_sweep.py --base-url http://<internal-runtime-redacted>:38081 --rate-limit-rpm 90
• route families are assembled in src/helpifyr_fabric/api/app.py
• route implementations are split across routes.py, identity_routes.py, plane_routes.py, support_routes.py, voice_routes.py, and combinations_routes.py
• Fabric-first agent bootstrap and access-answer routes are implemented in agent_routes.py

Unauthenticated 401 responses from :28080 do not prove that a route exists: the worker's auth middleware runs before route resolution. Use :38081 for public contract verification and require both a real 200 and the runtime-topology verifier's fake-route 404 control.

Server-error observability

The API emits one bounded uvicorn.error line for every returned or unhandled 5xx response. The line contains only the HTTP method, URL path (without query data), and status code; request headers, request/response bodies, and authorization values are never included. The repository regression path is:

python -m pytest tests/test_api.py -q

This proves the logging boundary locally. A live acceptance still requires an owner-authorized request that returns 5xx and a same-window docker logs jhf-fabric-api readback; repository verification does not claim that runtime gate.

Throttled Deep-Smoke Sweep

Use scripts/throttled_api_sweep.py for future broad GET-only API sweeps instead of ad hoc fast loops. The runner reads OpenAPI, substitutes deterministic smoke values for path parameters, respects a requests-per-minute budget, sleeps between batches, retries 429 responses with backoff, and writes optional JSON evidence.

Recommended <internal-runtime-redacted> command:

python3 scripts/throttled_api_sweep.py \
  --base-url http://<internal-runtime-redacted>:38081 \
  --rate-limit-rpm 90 \
  --batch-size 30 \
  --batch-sleep-seconds 20 \
  --retry-429 2 \
  --output /tmp/jhf-fabric-throttled-api-sweep.json

The sweep is read-only. Parameter-sample-dependent 404 and 422 responses stay classified separately from failures, while exhausted 429, transport errors, unresolved path parameters, and 5xx responses fail the run.

Available Now

Stalwart management admission

• POST /api/v1/identity/stalwart-management/projection
• GET /api/v1/identity/stalwart-management/decision

Fabric durably projects only fresh, active, human Spindle administrator truth for the stalwart_management surface. The producer and consumer use separate scoped tokens and missing or ambiguous exact-scope reads deny access. See docs/contracts/HELPIFYR_STALWART_MANAGEMENT_PROJECTION.md.

Core and governance routes

• GET /health
• Health responses include status, service, and the configured deployment_role (control-api, platform-api, test, or unknown when unset).
• GET /api/v1/platform/services
• GET /api/v1/contracts/*
• GET /api/v1/semantic/projection-verification-harness
• GET /api/v1/acp/contracts/*
• POST /api/v1/contracts/compatibility/check
• POST /api/v1/tools/admission/dry-run
• GET /api/v1/governance/*

Purpose:

• publish contract catalogs, drift, governance posture, and additive admission results
• keep semantic knowledge extensions on the same canonical dry-run lane instead of introducing a parallel onboarding surface
• publish only the S0 admission contract for the Bobbin-owned projection verification harness; this readback does not expose an ingress, database access, or agent-visible action

Identity and access routes

• GET /api/v1/identity/contracts/*
• GET /api/v1/identity/agent-federation/*
• POST /api/v1/warp/context
• GET /api/v1/projections/plane-unified-access*
• GET /api/v1/agent/contracts*
• GET /api/v1/agent/workflow
• GET /api/v1/agent/bootstrap
• GET /api/v1/agent/action-context/{module_key}
• GET /api/v1/agent/methodology/event-modeling

Purpose:

• publish deterministic identity policy, access handoff, agent-federation, and authz projection truth
• publish deterministic Fabric-first agent bootstrap, workflow, owner-matrix, task-to-tool, access-answer, usage, and methodology truth

Tooling, products, and update routes

• GET /api/v1/tools/*
• POST /api/v1/products/register
• GET /api/v1/products/*
• GET /api/v1/capabilities
• POST /api/v1/updates/check
• POST /api/v1/updates/rollout-gate
• POST /api/v1/integrations/gitea/webhook

Purpose:

• normalize repo/tool metadata, expose compatibility views, and accept guarded intake

Provider, runtime, and platform routes

• GET /api/v1/providers/openclaw/*
• GET /api/v1/dapr/*
• POST /api/v1/dapr/state/probe
• POST /api/v1/dapr/invocation/self-health/probe
• GET /api/v1/persistence/*
• GET /api/v1/observability/*
• GET /api/v1/recovery/*
• GET /api/v1/security/*
• GET /api/v1/signoff/*

Purpose:

• expose runtime dependency posture, provider observations, security, recovery, and operator signoff state

Product-domain contract routes

• GET /api/v1/combinations/*
• GET /api/v1/support-orchestration/*
• GET /api/v1/voice/*
• GET /api/v1/planning/contracts
• GET /api/v1/planning/interaction-lanes
• GET /api/v1/planning/interaction-lanes/create-session
• GET /api/v1/planning/interaction-lanes/answer-turn
• GET /api/v1/planning/interaction-lanes/owner-decision
• GET /api/v1/planning/sessions/{session_id}
• GET /api/v1/planning/sessions/{session_id}/review-bundle
• GET /api/v1/planning/sessions/{session_id}/owner-decision
• POST /api/v1/planning/sessions/{session_id}/owner-decision
• GET /api/v1/planning/interaction-lanes/start-review-round
• POST /api/v1/planning/sessions/{session_id}/review-rounds
• GET /api/v1/planning/interaction-lanes/owner-decision
• GET /api/v1/planning/sessions/{session_id}/owner-decision
• POST /api/v1/planning/sessions/{session_id}/owner-decision
• GET /api/v1/planning/sessions/{session_id}/score-gate
• GET /api/v1/planning/sessions/{session_id}/materialization-admission
• GET /api/v1/planning/sessions/{session_id}/execution-context
• GET /api/v1/planning/sessions/{session_id}/revision-ledger
• GET /api/v1/planning/sessions/{session_id}/resume-state

For dynamic Phase-1 sessions, the reviewer-round action creates only a Fabric-owned, redacted package intent and append-only round readback. The response is not provider execution, score approval, HIDL, materialization or execution authority. Shuttle remains the transport owner, and missing owner-service or Keystore truth stays explicitly awaiting_shuttle_owner/fail-closed.

For dynamic Plan Studio sessions, the owner-decision surface binds the existing contracts/operator_lanes/operator_lane_owner_decision_v1.json contract to the current planning-session revision. It exposes approved, rejected and needs_more_context with deterministic resume posture, but remains non-actionable until score, HIDL and owner-packet source readbacks are present. A recorded decision does not grant materialization, provider execution or domain-write authority.

• GET /api/v1/planning/events/catalog
• GET /api/v1/memory/runtime-claims/*
• GET /api/v1/events/publishing/*
• POST /api/v1/events/outbox/*

Purpose:

• publish product-adjacent contract truth, including the read-only Plan Studio Phase-0 planning family, and record event/evidence flows where Fabric owns the publication path

Optional / Extended

• platform-plane-specific routes and assets that matter only when Wiki.js and observability services are deployed
• provider preview routes that explain possible actions without directly mutating host state
• product-specific surfaces used only when corresponding consumers exist

Planned / Not In Current Scope

• later governance waves and downstream behaviors not yet implemented
• any undocumented route or contract behavior must be treated as not in current scope until it exists in code and verification

Public Surfaces

Common high-value endpoints for operator and consumer usage:

• GET /health
• GET /api/v1/contracts/registry
• GET /api/v1/contracts/drift
• GET /api/v1/acp/contracts/capability-registry
• GET /api/v1/acp/contracts/skill-pack-events
• GET /api/v1/acp/contracts/agent-handoff-events
• GET /api/v1/acp/projections/reed-read-only-capability
• GET /api/v1/acp/projections/swatch-scenario-verdict
• GET /api/v1/acp/projections/agent-handoff-ownership
• GET /api/v1/acp/contracts/tool-action-registry
• GET /api/v1/acp/assertions/reed-context-capability/{tool_name}
• CRM assertions require fresh tenant_id, company_id, environment, and adapter_instance_id query parameters; unknown companies are denied before upstream.
• GET /api/v1/acp/contracts/tool-execution-evidence
• GET /api/v1/contracts/jarvis
• GET /api/v1/combinations/profiles
• GET /api/v1/identity/contracts/access-mapping
• GET /api/v1/identity/contracts/entitlement-policy
• GET /api/v1/identity/contracts/surface-admission
• GET /api/v1/identity/contracts/surface-access
• GET /api/v1/identity/contracts/surface-lifecycle
• GET /api/v1/identity/consumers/onboarding
• POST /api/v1/identity/jadda-entitlement/projection
• GET /api/v1/identity/jadda-entitlement/decision
• GET /api/v1/identity/agent-federation/readiness
• GET /api/v1/projections/plane-unified-access/readiness
• GET /api/v1/platform/version-truth
• GET /api/v1/platform/projection-catalog
• GET /api/v1/platform/oss-security-readback
• GET /api/v1/platform/tool-oss-inventory-directory
• GET /api/v1/tools/host-pressure-policy
• GET /api/v1/mcp/grafana-readonly
• GET /api/v1/event-modeling/standard
• GET /api/v1/event-modeling/catalog
• GET /api/v1/event-modeling/issue-spec-export
• GET /api/v1/planning/contracts
• GET /api/v1/planning/interaction-lanes
• GET /api/v1/planning/interaction-lanes/create-session
• GET /api/v1/planning/interaction-lanes/answer-turn
• GET /api/v1/planning/sessions/{session_id}
• GET /api/v1/planning/sessions/{session_id}/review-bundle
• GET /api/v1/planning/sessions/{session_id}/score-gate
• GET /api/v1/planning/sessions/{session_id}/materialization-admission
• GET /api/v1/planning/sessions/{session_id}/execution-context
• GET /api/v1/planning/sessions/{session_id}/revision-ledger
• GET /api/v1/planning/sessions/{session_id}/resume-state
• GET /api/v1/planning/events/catalog
• GET /api/v1/events/issue-spec-export/contracts
• GET /api/v1/event-modeling/readiness
• GET /api/v1/event-modeling/standard-health-report
• GET /api/v1/event-modeling/companion-surfaces-contract
• GET /api/v1/event-modeling/audit-aggregation-contract
• GET /api/v1/event-modeling/tenant-bootstrap-contract
• GET /api/v1/agent/contracts
• GET /api/v1/agent/contracts/workflow
• GET /api/v1/agent/workflow
• GET /api/v1/agent/bootstrap
• GET /api/v1/agent/action-context/{module_key}
• GET /api/v1/agent/methodology/event-modeling
• GET /api/v1/tools/runtime-status
• GET /api/v1/providers/openclaw/runtime-status
• GET /api/v1/observability/readiness
• GET /api/v1/recovery/readiness

Contract Families

The API publishes data from:

• contracts/
• docs/contracts/
• runtime composition under deploy/compose/
• repo metadata such as fabric-manifest.json

OpenAPI is the machine-readable contract envelope, but route meaning is also anchored by the JSON contract artifacts and docs pages.

For platform OSS upgrade governance, Fabric now publishes one canonical version-truth surface plus one canonical projection-catalog surface instead of expecting Beam or other consumers to infer Grafana, Prometheus, Wiki.js, Dapr, n8n, or NATS pins, readback routes, or compatibility surfaces from distributed compose/docs history:

• GET /api/v1/platform/version-truth
• GET /api/v1/platform/projection-catalog
• GET /api/v1/platform/tool-oss-inventory-directory
• contracts/platform/platform_version_truth.json
• contracts/platform/platform_projection_catalog.json
• docs/contracts/HELPIFYR_PLATFORM_VERSION_TRUTH.md
• docs/contracts/HELPIFYR_PLATFORM_PROJECTION_CATALOG.md
• docs/contracts/HELPIFYR_PLATFORM_OSS_SECURITY_READBACK.md
• contracts/platform/platform_oss_security_readback_contract_v1.json

For cross-repo runtime gating on weak or shared hosts, Fabric now publishes one canonical host-pressure policy surface so runtime materialization and deployment repos do not invent repo-local CPU, memory, swap, or kswapd thresholds:

• GET /api/v1/tools/host-pressure-policy
• contracts/runtime/host_pressure_policy_v1.json
• contracts/runtime/host_pressure_policy_evidence_v1.schema.json
• docs/contracts/HELPIFYR_HOST_PRESSURE_POLICY.md

For ACP Wave 0/Wave 1 contract truth, Fabric now publishes one canonical capability-registry and skill-pack event-family surface so Reed and Warp consume explicit repository-standard Manifest v2 coupling, Reed-lane admission coupling, projection semantics, and fail-closed behavior instead of reconstructing them from backlog or local repo memory:

• GET /api/v1/acp/contracts/capability-registry
• GET /api/v1/acp/contracts/skill-pack-events
• GET /api/v1/acp/projections/reed-read-only-capability
• GET /api/v1/acp/projections/swatch-scenario-verdict

For Event Modeling Wave 1 core publication, Fabric now publishes one canonical pilot-catalog plus one issue-spec export surface so Shuttle and Warp consume the same serial-first Wave-1 truth instead of reconstructing sequencing from issue comments or chat history:

• GET /api/v1/event-modeling/standard
• GET /api/v1/event-modeling/catalog
• GET /api/v1/event-modeling/issue-spec-export
• GET /api/v1/events/issue-spec-export/contracts
• GET /api/v1/event-modeling/readiness
• GET /api/v1/event-modeling/standard-health-report
• GET /api/v1/event-modeling/companion-surfaces-contract
• GET /api/v1/event-modeling/audit-aggregation-contract
• GET /api/v1/event-modeling/tenant-bootstrap-contract
• contracts/event_modeling/event_modeling_issue_spec_export.json
• contracts/event_modeling/event_modeling_standard_health_report.json
• contracts/event_modeling/event_modeling_companion_surfaces_contract.json
• contracts/event_modeling/event_modeling_audit_aggregation_contract.json
• contracts/event_modeling/event_modeling_tenant_bootstrap_contract.json
• docs/event-models/agent-task-delegation/manifest.json
• contracts/acp/capability_registry_v1.json
• contracts/acp/skill_pack_event_families_v1.json
• contracts/acp/reed_read_only_projection_v1.json
• contracts/acp/swatch_scenario_verdict_projection_v1.json
• docs/contracts/HELPIFYR_ACP_CAPABILITY_REGISTRY_V1.md
• docs/contracts/HELPIFYR_ACP_REED_READ_ONLY_PROJECTION_V1.md
• docs/contracts/HELPIFYR_ACP_SWATCH_SCENARIO_VERDICT_PROJECTION_V1.md

For Wave 4 adoption parity, Fabric also publishes one canonical contract descriptor surface for later-wave issue-spec consumers so Bobbin and adjacent repos can discover the single authoritative export path instead of probing undocumented alternatives:

• GET /api/v1/events/issue-spec-export/contracts
• GET /api/v1/event-modeling/issue-spec-export

For Plan Studio Phase-0 live integration, Fabric now publishes one canonical read-only planning-session family plus one explicit interaction-lane catalog so Lantern, Pattern, Shuttle, Warp, and OpenClaw read live session, review, score-gate, materialization-admission, execution-context, revision-ledger, resume-state, event-vocabulary, and compose-lane admission truth from Fabric instead of inferring it from docs, chat, or repo-local fixture state:

• GET /api/v1/planning/contracts
• GET /api/v1/planning/interaction-lanes
• GET /api/v1/planning/interaction-lanes/create-session
• GET /api/v1/planning/interaction-lanes/answer-turn
• GET /api/v1/planning/sessions/{session_id}
• GET /api/v1/planning/sessions/{session_id}/review-bundle
• GET /api/v1/planning/sessions/{session_id}/score-gate
• GET /api/v1/planning/sessions/{session_id}/materialization-admission
• GET /api/v1/planning/sessions/{session_id}/execution-context
• GET /api/v1/planning/sessions/{session_id}/revision-ledger
• GET /api/v1/planning/sessions/{session_id}/resume-state
• GET /api/v1/planning/events/catalog
• contracts/planning/plan_studio_planning_session_v1.json
• contracts/planning/plan_studio_create_session_lane_v1.json
• contracts/planning/plan_studio_answer_turn_lane_v1.json
• contracts/planning/plan_studio_review_bundle_v1.json
• contracts/planning/plan_studio_score_gate_policy_v1.json
• contracts/planning/plan_studio_materialization_admission_v1.json
• contracts/planning/plan_studio_execution_context_v1.json
• contracts/planning/plan_studio_revision_ledger_v1.json
• contracts/planning/plan_studio_session_resume_policy_v1.json
• contracts/planning/plan_studio_event_catalog_v1.json
• contracts/planning/plan_studio_producer_consumer_matrix_v1.json
• docs/contracts/HELPIFYR_PLAN_STUDIO_CONTRACT_FAMILY.md
• python scripts/check_event_modeling_wave4_adoption.py --check-live --fabric-base-url http://<internal-runtime-redacted>:28080

The same GET /api/v1/event-modeling/issue-spec-export surface now also carries the bounded phase0_scenarios section for Plan Studio. That additive block is read-only and documents the dry-run planning flow only; it must not be treated as live issue-materialization or execution-readiness truth.

The planning-session family now also carries consumer-safe detail projection for operator tabs:

• current revision detail on GET /api/v1/planning/sessions/{session_id}
• reviewer-summary and round-synthesis review detail projection on GET /api/v1/planning/sessions/{session_id}/review-bundle
• suggested issue/wave refs plus admitted action intents on GET /api/v1/planning/sessions/{session_id}/execution-context
• append-only timeline and evidence-entry projection on GET /api/v1/planning/sessions/{session_id}/revision-ledger

Where detail truth is not yet safe or complete for downstream publication, the surfaces stay explicit and fail closed with projection-state markers instead of falling back to fixture/demo detail.

The interaction-lane catalog makes one additional boundary explicit: the generic admitted docs-change write posture still does not imply broad interactive compose authority. create_session and answer_turn are now admitted only as bounded Fabric-owned runtime session writes for Lantern BFF consumption, with dedicated POST routes, request/response DTO contracts, and explicit authority/auth truth for those actions.

For Event Modeling v2.0 execution-safety and consumer-governance truth, Fabric additionally publishes:

• GET /api/v1/event-modeling/standard-health-report
• GET /api/v1/event-modeling/companion-surfaces-contract
• GET /api/v1/event-modeling/audit-aggregation-contract
• GET /api/v1/event-modeling/tenant-bootstrap-contract

These surfaces provide read-only truth for:

• Dobby-backed standard evolution metrics
• companion-surface read permissions and prohibited behaviors
• audit-safe aggregation boundaries
• tenant bootstrap defaults and module-onboarding linkage

The companion contracts now also publish the explicit codex-companion passive-supervision lane. That consumer may read Fabric Event Modeling truth for closeout-readiness, drift visibility, and bounded supervision summaries, but it must remain fail-closed on sync conflict, may not self-close work by projection, and may not create shadow execution or blocker ownership outside Fabric gates.

For Fabric-first agent bootstrap and access-answer truth, Fabric now also publishes one canonical agent contract catalog plus one role-filtered bootstrap context and one module-scoped action-context surface so agents ask Fabric first instead of inferring stack behavior from scattered repo docs:

• GET /api/v1/agent/contracts
• GET /api/v1/agent/contracts/owner-matrix
• GET /api/v1/agent/contracts/capability-module-map
• GET /api/v1/agent/contracts/task-tool-selection
• GET /api/v1/agent/contracts/access-answers
• GET /api/v1/agent/contracts/tool-usage
• GET /api/v1/agent/contracts/dobby-learning-signal
• GET /api/v1/agent/contracts/workflow
• GET /api/v1/agent/workflow
• GET /api/v1/agent/bootstrap
• GET /api/v1/agent/action-context/{module_key}
• GET /api/v1/agent/methodology/event-modeling
• contracts/agent/agent_truth_layer_v1.json
• contracts/agent/agent_workflow_phase_contract_v1.json
• docs/contracts/HELPIFYR_AGENT_BOOTSTRAP_TRUTH_LAYER.md
• docs/contracts/HELPIFYR_AGENT_WORKFLOW_PHASE_CONTRACT.md

For ACP Wave 2 contract truth, Fabric now also publishes one canonical tool/action registry and one canonical execution-evidence/event family surface so consumers do not create local shadow tool/action truth for approval, dry-run, rollback, or evidence semantics:

• GET /api/v1/acp/contracts/tool-action-registry
• GET /api/v1/acp/contracts/tool-execution-evidence
• contracts/acp/tool_action_registry_v1.json
• contracts/acp/tool_execution_evidence_v1.json
• docs/contracts/HELPIFYR_ACP_TOOL_ACTION_REGISTRY_V1.md

For ACP Wave 4 contract truth, Fabric now also publishes one canonical handoff/escalation/ownership event catalog and one matching ownership projection so consumers do not invent local delegation or owner-selection truth when handoff event chains are missing, stale, circular, or conflicting:

• GET /api/v1/acp/contracts/agent-handoff-events
• GET /api/v1/acp/projections/agent-handoff-ownership
• contracts/acp/agent_handoff_event_catalog_v1.json
• contracts/acp/agent_handoff_ownership_projection_v1.json
• docs/contracts/HELPIFYR_ACP_AGENT_HANDOFF_EVENT_CATALOG_V1.md

For SSO-v4 surfaces, the API now also exposes explicit special-admin posture truth:

• surface-access publishes machine-readable admin_capable_surface and admin_postures
• consumers/onboarding mirrors the same superadmin and recovery-only admin posture for downstream consumers
• surface-lifecycle defines the audit-evidence event vocabulary for surface-superadmin-elevated and surface-recovery-admin-elevated

Producer / Consumer Zuordnung

• producer: jhf-fabric
• consumers: downstream JHF repos, Wiki.js docs publishing, operators, CI, provider integrators
• rule: consumers must not infer or redefine blocked/degraded/stale/conflict semantics beyond what Fabric already publishes

Compatibility Window

• current route families are versioned under /api/v1
• additive extension is preferred over incompatible rename or shape drift
• compatibility and admission are explicit route families, not undocumented conventions

Lifecycle Status

• active, verified, and used as the shared truth publication surface
• some preview families remain intentionally preview-only

Readiness / Drift / Monitoring

Typical route-check order:

1. GET /health
2. GET /api/v1/contracts/drift
3. GET /api/v1/observability/readiness
4. GET /api/v1/security/readiness
5. GET /api/v1/recovery/readiness
6. subsystem-specific readiness routes relevant to the current consumer

Deployment / Verify

• local API start: uvicorn helpifyr_fabric.api.app:app --reload
• OpenAPI export: GET /api/v1/openapi.json
• test coverage: tests/test_api.py plus subsystem-specific tests
• live host verification: route reads against the owner-declared Fabric runtime authority

Known Limits

• not every consumer needs every route family
• some route families summarize deeper contract documents and should be read alongside their matching docs pages
• preview endpoints must not be mistaken for direct mutation authority

Exceptions / Waivers

• local dev/test paths can differ from guarded live-host auth posture
• provider-derived runtime observations inform API output but do not replace Fabric-owned contract truth

Related Issues

• route and contract history is reflected in docs/issues/
• contract plans live under docs/plans/

License

• License: AGPLv3
• Project: https://helpifyr.com