API Reference

API And Public Surfaces

Tool / Contract Summary

jhf-bobbin does not expose a public Bobbin-owned HTTP API, webhook endpoint, or MCP service. Its public and testable surfaces remain CLI scripts, file contracts, machine-readable manifests, packaging artifacts, and validator outputs.

For the semantic-graph pilot foundation, Bobbin now defines an internal-only resident semantic runtime surface for health, readiness, and status readback. Those shadow-foundation ports are loopback-bound by default until the later runtime-owner rollout admits anything broader.

Business Value

• gives operators and QA a clear inventory of what can be called or validated
• prevents README and integration docs from becoming an unstructured endpoint dump
• makes it explicit which runtime APIs are consumed from other systems instead of owned locally

Current Verified State

Available and repo-validated surfaces include:

• Python and shell CLI entrypoints in scripts/
• machine-readable manifests and config contracts
• package build/publish/verify scripts
• repo-local and optional live runtime verification paths

Available Now

Exposed Repo-Owned CLI Surfaces

Surface	Type	Purpose
bash scripts/bootstrap.sh	shell	bootstrap installer configuration
bash scripts/install_jhf_memory.sh	shell	install or re-materialize the Bobbin runtime stack
bash scripts/reapply_after_openclaw_update.sh	shell	restore Bobbin state after OpenClaw updates
bash scripts/plugin_smoke_test.sh	shell	bounded runtime smoke validation
bash scripts/qdrant_checks.sh	shell	Qdrant collection and search verification
bash scripts/fabric-selfcheck.sh	shell	repo-local contract and documentation selfcheck
python3 scripts/check_live_runtime_contract.py	python CLI	fail-closed live runtime verification
python3 scripts/export_host_runtime_snapshot.py	python CLI	read-only runtime snapshot export including Mem0 lane/cutover readback
python3 scripts/check_runtime_materialization_drift.py	python CLI	cross-layer runtime materialization drift verification
python3 scripts/export-fabric-metadata.py	python CLI	metadata export for downstream consumers
python3 scripts/export_fabric_status_bundle.py	python CLI	status bundle export for read-only consumers

Exposed File And Artifact Surfaces

Surface	Type	Purpose
fabric-manifest.json	manifest	canonical Bobbin identity, capabilities, dependencies, and consumed surfaces
configs/stack-contract.json	contract	canonical stack, ports, volumes, and startup/verify truth
docs/MODULE_FEATURES.md	contract	machine-readable QA feature registry
contracts/api/bobbin_semantic_openapi_v1.json	contract	machine-readable OpenAPI contract for the internal semantic foundation API
contracts/api/bobbin_semantic_asyncapi_v1.json	contract	machine-readable AsyncAPI contract for current and reserved semantic event channels
contracts/api/bobbin_semantic_cdc_v1.json	contract	machine-readable CDC baseline plus TS-01 traceability matrix for admitted and downstream-gated lanes
dist/package-metadata.json	artifact metadata	package delivery contract after build/publish

Optional / Extended

• live readback checks using --check-live variants for Fabric and runtime validators
• package publishing via Gitea Generic Packages
• host snapshot validation and operator-run evidence export
• Mem0-v2 lane, rollback-window, and legacy-retirement readback via the host snapshot JSON

Planned / Not in Current Scope

• no public Bobbin-owned REST API
• no Bobbin-owned inbound webhook contract
• no Bobbin-owned queue consumer surface
• no Bobbin-owned MCP runtime service

Public Surfaces

Resident Service Surfaces

• GET /healthz on bobbin-semantic-api for internal health readback, loopback-bound by default
• GET /readyz on bobbin-semantic-api for internal readiness readback, loopback-bound by default
• GET /api/v1/semantic/runtime/status on bobbin-semantic-api for internal shadow-foundation status, loopback-bound by default, with ETag support and readback for activation stage, the non-secret monitoring_profile and canary_tenant_id, declared foundations, control-db discovery, graph-store loopback ports, and the non-secret Graphiti runtime profile including its admitted base_url, the admitted graph-search lane posture, a bounded authenticated Neo4j schema-integrity receipt, and the resident reconciliation-worker snapshot sourced from projection_reconciliation_readback plus repair receipts from projection_reconciliation_receipts. It is not a generic graph-admin surface.
• GET /api/v1/semantic/context/readback on bobbin-semantic-api for loopback-only Universal Work context availability. It returns no domain snippets or caller-provided context: only Bobbin-owned provenance, current freshness, schema-derived degradation and explicit false authority-boundary flags. Fabric remains the policy owner for whether this evidence is sufficient for a specific intent.
• GET /api/v1/semantic/topology/metrics/readback on bobbin-semantic-api for operator-only TS-11 topology evidence. It requires X-Bobbin-Operator-Token, returns only six allowlisted numeric metrics from the runtime-owner artifact, and marks unavailable evidence explicitly. It is loopback-only, agent-invisible, read-only, and is not a Prometheus, debug, configuration, or host-probing endpoint.
• POST /api/v1/semantic/projection-verification/runs on bobbin-semantic-api for the Fabric-admitted TS-02 S0 projection verification receipt. It requires X-Bobbin-Operator-Token and a runtime-injected allowlist of admitted ts02: case refs, accepts only correlation/source-event identifiers plus the case ref, derives fixture tenant and namespace server-side, and returns deterministic state, idempotency, reconciliation, replay/rebuild, latency, cleanup and residual-scan receipts with a one-hour maximum TTL. It is loopback-only, agent-invisible, normal-tenant-invisible, synthetic-only, fail-closed when admission is absent, and never performs projection or accesses a database, graph, vector store, host, provider, model or runtime state.
• POST /api/v1/semantic/fixtures/deletion-restore on bobbin-semantic-api for the operator-authenticated TS-09 S0 synthetic fixture. It accepts only an admitted synthetic fixture identifier and subject or tenant scope type, derives every scope key server-side, and returns deterministic ordered-lifecycle, shared-fact, backup/restore, no-resurrection, legal-hold, retention, tombstone/reapply, and zero-residual policy receipts. These are explicitly synthetic assertions, not live execution. It is loopback-only, agent-invisible, fixture-only, and never deletes data, runs backup or restore, or mutates a graph, vector store, cache, host, or runtime.
• POST /api/v1/semantic/fixtures/temporal-ontology on bobbin-semantic-api for the operator-authenticated TS-04 S0 synthetic fixture. It accepts only an admitted synthetic fixture identifier, derives deterministic temporal-state, derivation-authority and shadow-migration/rollback evidence server-side, and never reads or changes facts, namespaces, data stores, or runtime state.
• POST /api/v1/semantic/fixtures/entity-conflict on bobbin-semantic-api for the operator-authenticated TS-03 S0 synthetic fixture. It accepts only a synthetic fixture identifier and admitted scenario, derives exact-only, candidate-only, no-winner or reviewed merge/split posture server-side, and never resolves entities, changes aliases, facts, edges, namespaces, data stores or runtime state.
• POST /api/v1/semantic/fixtures/retrieval-gate on bobbin-semantic-api for the operator-authenticated TS-05 S0 synthetic fixture. It accepts only an admitted synthetic fixture identifier and fixed scenario, derives hybrid/degradation policy evidence server-side, and never searches data, reads vectors, calls a provider/model, changes a store or mutates runtime. Runtime metrics remain explicit unavailable until separately materialized through the canonical runtime-owner path.
• python3 scripts/verify_ts05_retrieval_gates.py verifies the TS-05 fixture receipt and, only at S1_read_only, evaluates a validated redacted runtime-owner receipt supplied through --runtime-owner-receipt-file against the fixed quality, P95, error-rate, and warm-cache thresholds. The receipt must identify jhf-openclaw-env, a source/run/receipt identity, redaction posture, and an executed composed-result reference. S0 fixture fields, including composed_result_executed, and the deprecated --metrics-file input never promote runtime evidence. Missing metrics are never converted to zero; Stage 2 reranker evidence remains optional and non-blocking.
• python3 scripts/verify_isolation_domain_walls.py --check verifies the K1 isolation-domain walls (jhf-bobbin#517, #546): the fifteen-domain PLAN_SELVAGEv4.3.1 baseline plus the governed customer_relationship extension are pinned and enforced, ingest refuses a missing or unknown isolation_domain_ref (QUARANTINED, no permissive default), the control-DB column/CHECK and worker merge persist the declared domain, both graph reads bind tenant hash plus the domain and drop any row or edge outside the requested compartment, and the explanation trace records the isolation_domain_wall step. It is deterministic and has no live dependencies.
• POST /api/v1/semantic/fixtures/context-security on bobbin-semantic-api for the operator-authenticated TS-06 S0 synthetic fixture. It derives only allowlisted authorization, tenant-denial, inference-risk, explanation and negative-state receipts. It accepts no principal, tenant, query, facts, vectors, model or provider input and never assembles, queries or changes context, graph, vector, cache or runtime data.
• POST /api/v1/semantic/fixtures/poison-mutation on bobbin-semantic-api for the operator-authenticated TS-12 S0 synthetic fixture. It accepts only a synthetic fixture identifier and a fixed poisoning, counterfactual or mutation label, derives containment, downgrade or rejection evidence server-side, and never reads real content, facts, vectors, documents, providers, models or runtime state.
• POST /api/v1/semantic/fixtures/canary-activation on bobbin-semantic-api for the operator-authenticated TS-13 S0 synthetic fixture. It derives only paired-baseline, low-risk read-only canary and stage-regression policy receipts. It never splits traffic, reads tenant data, calls a provider/model, activates S1+, permits actions or mutates runtime.

Consumed Runtime APIs

Upstream Surface	Purpose	Ownership
GET /readyz on LocalAI	readiness confirmation	target runtime
GET /v1/models on LocalAI	model presence verification	target runtime
POST /v1/embeddings on LocalAI	embedding generation	target runtime
Qdrant collection/search endpoints	vector store bootstrap and recall verification	target runtime
Fabric contract/readiness endpoints	governance and claims truth consumption	jhf-fabric

Contract Families

Fabric-owned families consumed read-only are documented in:

• Fabric Tool Profile (docs/FABRIC_TOOL_PROFILE.md)
• Memory Policy and Claims Consumption (docs/MEMORY_POLICY_AND_CLAIMS_CONSUMPTION.md)
• Integrations

Producer-/Consumer-Zuordnung

• Bobbin produces:
  • CLI outputs
  • validation results
  • exported metadata/status artifacts
  • package metadata
• Bobbin consumes:
  • OpenClaw runtime configuration
  • LocalAI and Qdrant runtime APIs
  • Fabric governance/claims/readiness surfaces

Compatibility Window

• version truth: tag v0.x.y or derived 0.0.0+<shortsha>
• interface stability: stable for documented CLI/contract surfaces, operator-bounded for live host flows

Lifecycle Status

• repo-owned public surfaces: active
• public resident service API: intentionally absent
• internal shadow-foundation runtime API: defined but not externally admitted
• resident reconciliation worker: internal-only, admission-plus-visibility-repair-only for bounded control-db reconciliation, and not a public Bobbin queue consumer surface
• machine-readable API/event/CDC contracts: published for contract-first coordination without widening public runtime admission

Published Machine-Readable API Contracts

• OpenAPI: contracts/api/bobbin_semantic_openapi_v1.json
• AsyncAPI: contracts/api/bobbin_semantic_asyncapi_v1.json
• CDC baseline: contracts/api/bobbin_semantic_cdc_v1.json

TS-01 CDC Traceability

ts01_consumer_matrix keeps the scope boundary executable. Reed, Lantern, and Beam are the only admitted current consumers of the internal runtime-status surface. Fabric, Heddle, Spindle, and Mem0/Graphiti-to-Infinity entries are downstream-gated and link to their owner issue and suite; they do not admit another endpoint or claim a green TS-01 result. Verify with python3 scripts/check_semantic_cdc_matrix.py.

Readiness / Drift / Monitoring

• use Operations for operational verify paths
• use Feature Registry (docs/MODULE_FEATURES.md) for QA-oriented test paths
• use Stack Container Contract (docs/STACK_CONTAINER_CONTRACT.md) for canonical stack truth

Deployment / Verify

bash scripts/fabric-selfcheck.sh
python3 scripts/check_docs_contract.py
python3 scripts/check_module_features_contract.py
python3 -m unittest -q tests/test_contracts.py

Known Limits

• CLI and file surfaces are repo-owned; runtime APIs are mostly upstream-owned
• host verification depends on operator access and running services

Related Issues

• JaddaHelpifyr/jhf-bobbin#59
• JaddaHelpifyr/jhf-bobbin#60
• JaddaHelpifyr/jhf-bobbin#74

AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.