Skip to main content

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>:38080 --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 :38080 for public contract verification and require both a real 200 and the runtime-topology verifier's fake-route 404 control.

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 Host172 command:

python3 scripts/throttled_api_sweep.py \
  --base-url http://<internal-runtime-redacted>:38080 \
  --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
  • 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
  • route and contract history is reflected in docs/issues/
  • contract plans live under docs/plans/

License​