Skip to main content

jhf-spool Integrations

Documentation Map​

Integrations

Version: 2026-04-01

Scope​

This document lists maintained integrations only.

  • Legacy or archived prototype surfaces are not supported integration anchors.
  • The maintained contract is Linux-first and HTTP-first.
  • Fabric should treat this document and fabric-manifest.json as repository-derived contract material, not as a live control plane.

Structure Contract​

Every integration entry below uses the same required fields:

  • Direction
  • Type
  • Surface
  • Auth
  • Stability
  • Versioning
  • Owner

Optional notes are kept short and only where needed.

Canonical Env and URL Contract​

  • Canonical stack/project prefix:

    • JHF_SPOOL_STACK_NAME (default jhf-spool)

  • Legacy compatibility alias (still accepted):

    • NEWS_MEMORY_STACK_NAME

  • Canonical runtime base/public URLs:

    • NEWS_MEMORY_API_BASE_URL (downstream caller base, for example n8n -> API)
    • NEWS_MEMORY_PUBLIC_BASE_URL (public URL used for externally visible links and redirect logic)

  • Canonical trust and proxy controls:

    • NEWS_MEMORY_TRUSTED_HOSTS
    • NEWS_MEMORY_FORCE_HTTPS_REDIRECT
    • NEWS_MEMORY_TLS_HOSTS
    • NEWS_MEMORY_TLS_PORT

  • External URLs currently used by maintained live verification:

    • https://<internal-runtime-redacted>
    • v1/health
    • v1/health
    • v1/health
    • v1/fabric
    • v1/external-api-contract
    • https://<internal-runtime-redacted>/openapi.json
    • https://<internal-runtime-redacted>/docs
    • https://<internal-runtime-redacted>/redoc

Incoming Integrations​

Public discovery and contract reads​

  • Direction: incoming
  • Type: REST API
  • Surface:
    • GET /v1/health/live
    • GET /v1/health/ready
    • GET /v1/health/info
    • GET /openapi.json
    • GET /docs
    • GET /redoc
    • GET /v1/external-api-contract
    • GET /v1/fabric/metadata
    • GET /v1/release-notices
  • Auth: none
  • Stability: stable
  • Versioning: live/readiness/info under /v1; docs/openapi are derived from the maintained service contract
  • Owner: opsie (cicd-ops)
  • Notes:
    • this is the correct read-first discovery surface for a future Fabric consumer
    • /v1/health/info is the current version-adjacent runtime info surface; there is no dedicated /version endpoint
    • /v1/fabric/metadata is a read-only serialization of repository-maintained fabric metadata

Ingest API​

  • Direction: incoming
  • Type: REST API
  • Surface:
    • POST /v1/ingest/gdelt
    • POST /v1/ingest/ccnews
    • POST /v1/ingest/gdelt/backfill
    • POST /v1/ingest/ccnews/backfill
    • POST /v1/ingest/gdelt/current-events
    • POST /v1/ingest/ccnews/current-events
    • POST /v1/ingest/rss/backfill
    • POST /v1/ingest/rss/current-events
    • POST /v1/ingest/newsapi/backfill
    • POST /v1/ingest/newsapi/current-events
    • GET /v1/jobs/{job_id}
  • Auth: scoped API key
  • Stability: stable
  • Versioning: maintained /v1 contract
  • Owner: data-pipeliner
  • Notes:
    • create ingest jobs and read job status

Search API​

  • Direction: incoming
  • Type: REST API
  • Surface:
    • POST /v1/search/semantic
    • POST /v1/search/filter
    • GET /v1/articles/{article_id}
    • GET /v1/articles/{article_id}/versions
    • GET /v1/articles/{article_id}/dedupe-cluster
  • Auth: scoped API key
  • Stability: stable
  • Versioning: maintained /v1 contract
  • Owner: query-engineer
  • Notes:
    • clearest first-step consumer surface after health and OpenAPI

Export and research API​

  • Direction: incoming
  • Type: REST API
  • Surface:
    • POST /v1/datasets/snapshots
    • GET /v1/datasets/snapshots/{snapshot_id}
    • GET /v1/datasets/snapshots/{snapshot_id}/lineage
    • GET /v1/datasets/snapshots/{snapshot_id}/summary
    • GET /v1/datasets/snapshots/{snapshot_id}/replay-package
    • POST /v1/exports/simulation
    • GET /v1/exports/{export_id}
    • GET /v1/exports/{export_id}/manifest
    • GET /v1/exports/{export_id}/artifact
    • POST /v1/research/runs
    • GET /v1/research/runs/{run_id}
    • GET /v1/research/runs/{run_id}/compare
    • GET /v1/research/runs/{run_id}/comparison-standards
    • GET /v1/research/runs/{run_id}/compare/export
    • GET /v1/research/runs/{run_id}/compare/timeline
    • GET /v1/research/runs/{run_id}/impact
    • GET /v1/research/runs/{run_id}/impact/export
    • GET /v1/research/runs/{run_id}/bundle/export
    • GET /v1/research/runs/{run_id}/consumer-validation
  • Auth: export-capable, research-capable, or admin-capable scoped API key depending on route
  • Stability: stable
  • Versioning: maintained /v1 contract
  • Owner: backend-architekt
  • Notes:
    • implemented today
    • broader than the minimum Fabric read-first surface

Account and billing API​

  • Direction: incoming
  • Type: REST API
  • Surface:
    • GET|POST /v1/accounts/...
    • GET|POST /v1/auth/api-keys
    • GET /v1/auth/scope-matrix
    • GET /v1/credits
    • GET /v1/usage
    • GET|POST /v1/accounts/{account_id}/billing-periods
    • POST /v1/accounts/{account_id}/billing/checkout
    • POST /v1/accounts/{account_id}/billing/customer-portal
    • GET /v1/accounts/{account_id}/billing/subscriptions
    • GET /v1/accounts/{account_id}/billing/external-invoices
    • GET /v1/billing/external-invoices/{external_invoice_id}
    • GET /v1/billing/external-invoices/{external_invoice_id}/download
    • GET|POST /v1/billing-periods/{billing_period_id}/invoices
    • GET /v1/accounts/{account_id}/invoices
    • GET /v1/invoices/{invoice_id}
    • POST /v1/invoices/{invoice_id}/settle
    • GET /v1/billing/provider
    • GET /v1/pricing-plans
  • Auth: owner, billing-capable, admin, or account-bound scoped API key depending on route
  • Stability: stable
  • Versioning: maintained /v1 contract
  • Owner: backend-architekt
  • Notes:
    • commercial live rollout still depends on real Paddle production configuration

Support API​

  • Direction: incoming
  • Type: REST API
  • Surface:
    • GET|POST /v1/accounts/{account_id}/support-cases
    • GET /v1/support-cases/{case_id}
    • GET /v1/support-cases/{case_id}/customer-view
    • POST /v1/support-cases/{case_id}/update
    • GET /v1/support-cases/{case_id}/evidence
    • POST /v1/support-cases/{case_id}/evidence/enrich
  • Auth: account-bound or admin-scoped API key
  • Stability: stable
  • Versioning: maintained /v1 contract
  • Owner: backend-architekt
  • Notes:
    • evidence is advisory and must never be treated as case truth
    • enrichment supports timeout/degraded/fallback boundaries plus replay-safe rerun via replay token
    • contract details: docs/SUPPORT_EVIDENCE_CONTRACT.md

Governance and runtime API​

  • Direction: incoming
  • Type: REST API
  • Surface:
    • GET /v1/research/operational-dashboard-summary
    • GET /v1/research/operational-slo-gates
    • GET /v1/research/security-compliance-gates
    • GET /v1/research/incident-readiness-gates
    • GET /v1/research/security-pen-test-evidence
    • GET /v1/research/tls-proxy-readiness
    • GET /v1/research/secret-readiness
    • GET /v1/research/paddle-readiness
  • Auth: admin or operator-oriented scoped API key
  • Stability: stable
  • Versioning: maintained /v1 contract
  • Owner: opsie (cicd-ops)
  • Notes:
    • internal/operator-facing, not part of the narrow external customer contract

Webhook ingress​

  • Direction: incoming
  • Type: Webhook
  • Surface:
    • POST /v1/webhooks/paddle
  • Auth: Paddle webhook signature secret
  • Stability: stable
  • Versioning: provider payload versioning plus maintained /v1 ingress path
  • Owner: backend-architekt

Web UI​

  • Direction: incoming
  • Type: Other
  • Surface:
    • GET /
    • GET /pricing
    • GET /developers
    • /auth/...
    • /app/...
  • Auth: signed cookie session for authenticated app sections
  • Stability: stable
  • Versioning: web UI follows the maintained service state; no separate semver surface
  • Owner: backend-architekt
  • Notes:
    • human-facing surface, not a preferred first Fabric integration anchor

Outgoing Integrations​

PostgreSQL runtime store​

  • Direction: outgoing
  • Type: Database contract
  • Surface: DATABASE_URL
  • Auth: runtime database credential
  • Stability: stable
  • Versioning: deployment-specific PostgreSQL version; no repository-owned database API version
  • Owner: infra-ops

MinIO artifact store​

  • Direction: outgoing
  • Type: File contract
  • Surface: MINIO_ENDPOINT
  • Auth: object-store credential
  • Stability: stable
  • Versioning: deployment-specific MinIO/S3-compatible runtime
  • Owner: infra-ops

Qdrant vector store​

  • Direction: outgoing
  • Type: Database contract
  • Surface: QDRANT_URL
  • Auth: internal runtime access
  • Stability: stable
  • Versioning: deployment-specific Qdrant runtime; repository assumes maintained payload compatibility
  • Owner: query-engineer

Redis runtime dependency​

  • Direction: outgoing
  • Type: Database contract
  • Surface: REDIS_URL
  • Auth: runtime Redis credential
  • Stability: stable
  • Versioning: deployment-specific Redis runtime
  • Owner: infra-ops

GDELT source​

  • Direction: outgoing
  • Type: REST API
  • Surface: maintained GDELT ingestion client path
  • Auth: none
  • Stability: stable
  • Versioning: provider-managed
  • Owner: data-pipeliner

Common Crawl CC-NEWS source​

  • Direction: outgoing
  • Type: REST API / object retrieval
  • Surface: maintained CC-NEWS ingestion client path
  • Auth: none
  • Stability: stable
  • Versioning: provider-managed
  • Owner: data-pipeliner

RSS sources​

  • Direction: outgoing
  • Type: Other
  • Surface: configured RSS feed URLs
  • Auth: feed-specific or public
  • Stability: stable
  • Versioning: provider-managed
  • Owner: data-pipeliner

NewsAPI source​

  • Direction: outgoing
  • Type: REST API
  • Surface: maintained NewsAPI ingestion client path
  • Auth: API key
  • Stability: stable
  • Versioning: provider-managed NewsAPI v1 contract
  • Owner: data-pipeliner

Bidirectional Integrations​

n8n workflow orchestration​

  • Direction: bidirectional
  • Type: REST API + CLI/file deployment support
  • Surface:
    • maintained News Memory API routes consumed by workflows
    • n8n-workflows/jhf-spool/*
    • scripts/deploy_news_memory_n8n_workflows.py
  • Auth: shared scoped API key plus deployment-time n8n credentials
  • Stability: stable
  • Versioning: maintained API under /v1; workflow compatibility is repository-managed and deployment-specific
  • Owner: n8n-workflow-specialist
  • Notes:
    • optional for the maintained core service

CLI and File Contracts​

Repository metadata and Fabric helpers​

  • Direction: incoming
  • Type: File contract / CLI
  • Surface:
    • fabric-manifest.json
    • docs/RUNTIME_CONTRACT.json
    • docs/STACK_CONTRACT.md
    • docs/FABRIC_TOOL_PROFILE.md
    • scripts/export-fabric-metadata.py
    • scripts/fabric-selfcheck.sh
  • Auth: repository read access, plus optional API access for selfcheck
  • Stability: stable
  • Versioning: repository-managed; tied to current branch and manifest schema
  • Owner: opsie (cicd-ops)

Operational helper scripts​

  • Direction: incoming
  • Type: CLI
  • Surface:
    • scripts/smoke-test.py
    • scripts/ops/run_live_platform_journey.py
    • scripts/ops/run_operational_release_checks.py
    • scripts/ops/run_host_release_check.py
    • scripts/ops/run_postgres_verify_suite.py
    • scripts/ops/mint_news_memory_agent_key.py
    • scripts/ops/run_constitutional_case.py
    • scripts/ops/review_constitutional_slice.py
    • scripts/ops/summarize_constitutional_case.py
  • Auth: depends on helper; usually API key or host access
  • Stability: stable
  • Versioning: repository-managed helper contract
  • Owner: opsie (cicd-ops)

Deployment resilience credential-rotation contract​

  • Direction: incoming
  • Type: File contract
  • Surface:
    • docs/CREDENTIAL_ROTATION_CONTRACT.md
    • scripts/ops/verify_spool_auth_rotation.py
    • tests/test_credential_rotation_consumer_contract.py
  • Auth: verification run requires valid and invalid search keys supplied by operator/CI
  • Stability: stable
  • Versioning: spool-auth-rotation-v1
  • Owner: opsie (cicd-ops)
  • Notes:
    • consumer-facing verify contract for deployment resilience paths
    • consumer is expected to gate on classification.decision

Legacy Surface​

Legacy webhook router​

  • Direction: incoming
  • Type: Webhook
  • Surface:
    • /webhooks/agent/{agent_name}
    • /webhooks/team/broadcast
    • /webhooks/health
    • /webhooks/agents
  • Auth: weak or implicit
  • Stability: legacy
  • Versioning: no maintained compatibility commitment
  • Owner: legacy / not recommended
  • Notes:
    • present in repository history
    • not a supported integration anchor

Implemented Fabric Read Surface​

Fabric metadata​

  • Direction: incoming
  • Type: REST API
  • Surface:
    • GET /v1/fabric/metadata
  • Auth: none
  • Stability: stable
  • Versioning: repository-derived from fabric-manifest.json; does not define a second independent API contract
  • Owner: opsie (cicd-ops)

Fabric Wave-3 governance contract consumption​

  • Direction: outgoing
  • Type: REST API
  • Surface:
    • GET api/v1/contracts/matrix
    • GET api/v1/contracts/docs-standard
    • referenced family surfaces from matrix entries relevant to jhf-spool
  • Auth: none (read-only)
  • Stability: stable
  • Versioning: accepted family version 1.0.0 for relevant Wave-3 governance families
  • Owner: opsie (cicd-ops)
  • Notes:
    • canonical family/version source is Fabric, not local docs
    • local adoption mapping lives in fabric-manifest.json (fabric_wave3_adoption) and FABRIC_WAVE3_ADOPTION.md (docs/FABRIC_WAVE3_ADOPTION.md)

Dobby v1 Classification​

Dobby integration posture (v1)​

  • Direction: incoming (optional consumer)
  • Type: REST API
  • Surface:
    • GET /v1/support-cases/{case_id}/evidence
    • POST /v1/search/semantic
    • POST /v1/search/filter
    • GET /v1/health/live
    • GET /v1/health/ready
    • GET /v1/fabric/metadata
  • Auth: scoped API key for search/evidence; none for public health/metadata
  • Stability: stable
  • Versioning: maintained /v1 contract
  • Owner: opsie (cicd-ops)
  • Notes:
    • canonical v1 classification is optional read-only evidence source
    • Dobby v1 is not required to integrate Spool as hard runtime dependency
    • Dobby v1 write/control integration into Spool is out of scope
    • source issues: solarisara/jhf-spool#85, JaddaHelpifyr/jhf-dobby#30, JaddaHelpifyr/jhf-dobby#32

Integrated Mode Preparation​

Shared-service attachment stance​

  • Direction: bidirectional (planned)
  • Type: Other
  • Surface:
    • fabric-manifest.json (mode_contract.integrated)
    • docs/INTEGRATED_MODE_CONTRACT.md
  • Auth: n/a (planning contract only)
  • Stability: planned
  • Versioning: tracked via manifest and docs revisions
  • Owner: opsie (cicd-ops)
  • Notes:
    • integrated mode is contract-prepared only
    • no shared heavy-store migration is implied

Fabric combination profile truth (consumer)​

  • Direction: outgoing
  • Type: REST API
  • Surface:
    • GET api/v1/combinations/profiles
    • scripts/ops/evaluate_fabric_combination_consumer.py
  • Auth: none (read-only)
  • Stability: stable
  • Versioning: Fabric-owned endpoint/version
  • Owner: opsie (cicd-ops) for consumer behavior, jhf-fabric for source truth
  • Notes:
    • jhf-spool consumes combination truth read-only
    • local heavy data-plane health can complement monitoring only and must not overwrite active combination truth

Adopt-first migration stance​

  • Direction: incoming
  • Type: File contract
  • Surface:
    • docs/ADOPT_FIRST_MIGRATION.md
  • Auth: repository read access
  • Stability: stable (documentation contract)
  • Versioning: repository revision
  • Owner: opsie (cicd-ops)

License: AGPLv3
Learn more: https://helpifyr.com