Skip to main content

API

Documentation Map​

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
  • health endpoint: /health
  • 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

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​

Core and governance routes​

  • GET /health
  • GET /api/v1/platform/services
  • GET /api/v1/contracts/*
  • 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

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/memory/runtime-claims/*
  • GET /api/v1/events/publishing/*
  • POST /api/v1/events/outbox/*

Purpose:

  • publish product-adjacent contract truth 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/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
  • 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/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/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

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
  • python scripts/check_event_modeling_wave4_adoption.py --check-live --fabric-base-url http://<internal-runtime-redacted>:28080

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

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 <internal-runtime-redacted>

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​