Zum Hauptinhalt springen

Build an Integration

Use this page when you need to connect a consumer, provider, repo, or operator workflow to Helpifyr through documented API, event, MCP, or repository-intake surfaces.

When to use this page​

  • You are integrating against Fabric-owned API or contract surfaces.
  • You need to understand integration boundaries before you implement credentials, payloads, or event handling.
  • You need public-safe integration guidance before dropping into exact product reference pages.

Prerequisites​

  • You know whether your integration is API, event, MCP, or repository-intake driven.
  • You can read the published Fabric API and integration documentation.
  • You understand that owner-approved contracts outrank ad-hoc assumptions.

Integration model​

Most Helpifyr integrations follow one of these patterns:

  • read-only control-plane API consumption
  • guarded write or intake calls through approved endpoints
  • event publication or observation through documented families
  • repository metadata and manifest intake
  • MCP readback or safe-action consumption through Fabric-owned boundaries

Architecture / Flow​

Step-by-step procedure​

1. Decide which integration family you need​

Before you write code, classify the integration:

  • control-plane API client
  • event consumer or event publisher
  • MCP consumer
  • repository-intake workflow
  • platform-plane or observability consumer

This matters because auth, stability, and owner rules differ by family.

2. Read the public-safe source pages first​

Start with:

These pages tell you:

  • which routes and families are already implemented
  • which integrations are internal, external, or read-only
  • what auth posture is expected
  • where Fabric is the context provider versus the mutation owner

3. Use the exact route family, not a guessed one​

Illustrative high-value read surfaces:

GET /api/v1/contracts/registry
GET /api/v1/contracts/drift
GET /api/v1/platform/projection-catalog
GET /api/v1/agent/contracts
GET /api/v1/agent/workflow
GET /api/v1/event-modeling/catalog
GET /api/v1/acp/contracts/capability-registry
GET /api/v1/tools/runtime-status

Choose the surface that matches the truth you need:

  • contracts and governance
  • agent bootstrap or workflow
  • event-modeling
  • ACP capability and handoff truth
  • runtime evidence

4. Validate auth and sensitivity before implementation​

From the security model:

  • summary and health surfaces may be low-risk read paths
  • /api/v1/* control-plane surfaces are generally api_key protected
  • webhook and rollout paths require stricter guards
  • MCP must not bypass Fabric auth or policy

Do not treat an internal example as public anonymous access.

5. Build against the exact documented surface​

Illustrative curl sequence:

curl -s <fabric-base-url>/api/v1/contracts/registry
curl -s <fabric-base-url>/api/v1/platform/projection-catalog
curl -s <fabric-base-url>/api/v1/agent/contracts
curl -s <fabric-base-url>/api/v1/event-modeling/catalog

Illustrative OpenAPI discovery:

GET /api/v1/openapi.json

Use the OpenAPI export when you need exact request and response structure, and the product docs pages when you need interpretation.

6. Verify integration posture before handoff​

After the consumer logic is in place, verify both platform and runtime posture:

GET /api/v1/observability/readiness
GET /api/v1/security/readiness
GET /api/v1/recovery/readiness

If the integration depends on runtime alignment, also run:

python ./scripts/verify_runtime_materialization.py --check

Example integration decision table​

  • Need exact route families and payload direction:
  • Need system-to-system relationship and ownership:
  • Need auth and sensitive-surface boundaries:

Verification​

An integration path is ready for the next implementation step when:

  1. the integration family is clearly classified
  2. the exact documented route or contract surface is identified
  3. auth posture is explicit
  4. readiness and security verification do not contradict the intended use
  5. the implementation does not rely on guessed or undocumented behavior

Common failure modes​

Building against a route discovered only from logs or memory​

Problem:

  • the integration is not anchored to stable docs truth.

Better path:

  • start from /api/v1/openapi.json and the public reference pages

Mixing read-only and guarded-write assumptions​

Problem:

  • a consumer is built with the wrong auth or risk model.

Better path:

Treating MCP as a bypass around policy​

Problem:

  • the integration undermines the control-plane boundary.

Better path:

  • use MCP only through the admitted Fabric-owned lane and its published purpose

Owner Handoff​

  • control-plane integration truth owner: JaddaHelpifyr/helpifyr-fabric
  • materialized docs workspace owner: JaddaHelpifyr/jhf-docs
  • downstream runtime and product actions remain owned by their respective repos

Source Truth​

Next paths​