API

Documentation Map

API

Scope

This file summarizes the stable and relevant HTTP surfaces for jhf-warp. It does not replace the live OpenAPI document at /openapi.json.

Canonical Self-Description Endpoints

Endpoint	Method	Purpose	Stability	Auth
`/health`	`GET`	liveness check	stable	deployment-time protection if needed
`/ready`	`GET`	readiness plus warnings/capabilities/self-description hints	stable	deployment-time protection if needed
`/version`	`GET`	canonical version endpoint plus manifest/version-source hints	stable	deployment-time protection if needed
`/fabric-manifest.json`	`GET`	read-only machine-readable repository/service manifest	stable	deployment-time protection if needed
`/api/v1/version`	`GET`	versioned API variant plus manifest/version-source hints	stable	deployment-time protection if needed
`/openapi.json`	`GET`	machine-readable OpenAPI document	stable	deployment-time protection if needed

These endpoints are read-only. They may sit behind the same operator/internal gateway boundary as the rest of the service, but they are the only endpoints that should ever be considered for broader read-only exposure. Their shared-host publication contract is explicit:

jhf-warp-api is static-required on host port 18086
the machine-readable publication source is GET /fabric-manifest.json -> runtime_contract.port_policy
Fabric and other consumers must not infer live ingress ports from Docker or ad-hoc host scans

Auth Boundary Classes

self-description:
- /health
- /ready
- /version
- /openapi.json
- /fabric-manifest.json
internal operator reads:
- runtime, topology, drift, audit, rollout, control-agent reads, persistent-agent reads, and /metrics
internal control or mutation:
- patch plan/apply
- execution apply routes
- control-agent reconcile and dispatch preview
- persistent-agent learning proposal writes and review writes

The application requires a Bearer token for internal routes and consumes projected authority context without turning Warp into a local IAM or governance authority. Heddle remains the upstream identity/auth truth, Fabric remains the current projection/composition layer, and future normative governance belongs to Spine. Self-description routes stay open. Outside development and test, mutating routes fail closed when the projected authority context is unavailable or incomplete.

Treat the second and third classes as deployment-protected internal surfaces even with the built-in token gate.

Primary API Groups

Classification and Setup

Endpoint group	Methods	Auth	Stability
`/api/v1/classify`	`POST`	Bearer token + projected authority context	stable
`/api/v1/setup/preview`	`POST`	Bearer token + projected authority context	stable
`/api/v1/domains`	`GET`	Bearer token + projected authority context	stable
`/api/v1/domains/{domain_id}/profiles`	`GET`	Bearer token + projected authority context	stable
`/api/v1/domains/{domain_id}/setup`	`POST`	Bearer token + projected authority context	stable

Runtime / Topology / Drift

Endpoint group	Methods	Auth	Stability
`/api/v1/runtime/inventory`	`GET`	Bearer token + projected authority context	stable
`/api/v1/topology/current`	`GET`	Bearer token + projected authority context	stable
`/api/v1/topology/diff`	`GET`	Bearer token + projected authority context	stable
`/api/v1/drift/summary`	`GET`	Bearer token + projected authority context	stable
`/metrics`	`GET`	Bearer token + projected authority context	stable
`/api/v1/openclaw/patch/plan`	`POST`	Bearer token + projected write authorization	stable
`/api/v1/openclaw/patch/apply`	`POST`	Bearer token + projected write authorization	stable

Agent Federation Runtime

Endpoint group	Methods	Auth	Stability
`/api/v1/agent-runtime/catalog`	`GET`	Bearer token + projected authority context	stable
`/api/v1/agent-runtime/catalog/{agent_id}`	`GET`	Bearer token + projected authority context	stable
`/api/v1/agent-runtime/team-handoff-policies`	`GET`	Bearer token + projected authority context	stable
`/api/v1/agent-runtime/team-handoff-policies/{agent_slug}`	`GET`	Bearer token + projected authority context	stable
`/api/v1/agent-runtime/delegations`	`GET`	Bearer token + projected authority context	stable
`/api/v1/agent-runtime/delegation-state`	`GET`	Bearer token + projected authority context	stable
`/api/v1/agent-runtime/readiness`	`GET`	Bearer token + projected authority context	stable

These routes are the deterministic federation read contract for Heddle/Fabric-facing consumers. They expose root agent ids, parentage status, runtime federation state, class-transition state, and fail-closed markers so downstream consumers do not need local heuristics for ambiguous parentage, multiple roots, degraded fallback, or zombie lockout.

GET /api/v1/agent-runtime/team-handoff-policies is the canonical ACP-W4 read-only surface for:

explicit team assignment mode
delegation scope and max depth
same-team versus cross-team handoff posture
accept/reject/expire/escalate transitions
circular-handoff fail-closed behavior
missing/stale/conflicting projection fail-closed posture

Audit / Rollout

Endpoint group	Methods	Auth	Stability
`/api/v1/audit/events`	`GET`	Bearer token + projected authority context	stable
`/api/v1/rollouts/audit`	`GET`	Bearer token + projected authority context	stable
`/api/v1/rollouts/history`	`GET`	Bearer token + projected authority context	stable

Control Agent

Endpoint group	Methods	Auth	Stability
`/api/v1/control-agent/status`	`GET`	Bearer token + projected authority context	stable
`/api/v1/control-agent/reconcile`	`POST`	Bearer token + projected write authorization	stable
`/api/v1/control-agent/leases`	`GET`	Bearer token + projected authority context	stable
`/api/v1/control-agent/watchdog`	`GET`	Bearer token + projected authority context	stable
`/api/v1/control-agent/schedule`	`GET`	Bearer token + projected authority context	stable
`/api/v1/control-agent/dispatch-preview`	`POST`	Bearer token + projected write authorization	stable

Persistent Domain Agents

Endpoint group	Methods	Auth	Stability
`/api/v1/persistent-agents`	`GET`	Bearer token + projected authority context	stable
`/api/v1/persistent-agents/{agent_slug}`	`GET`	Bearer token + projected authority context	stable
`/api/v1/persistent-agents/{agent_slug}/learning-proposals`	`GET`, `POST`	GET projected authority, POST projected write authorization	stable
`/api/v1/persistent-agents/{agent_slug}/learning-proposals/{proposal_id}/review`	`POST`	Bearer token + projected write authorization	stable
`/api/v1/tool-profiles`	`GET`	Bearer token + projected authority context	stable
`/api/v1/agent-tool-policies`	`GET`	Bearer token + projected authority context	stable
`/api/v1/agent-tool-policies/{agent_slug}`	`GET`	Bearer token + projected authority context	stable
`/api/v1/voice/targets`	`GET`	Bearer token + projected authority context	stable
`/api/v1/voice/targets/default`	`GET`	Bearer token + projected authority context	stable
`/api/v1/voice/targets/{agent_slug}`	`GET`	Bearer token + projected authority context	stable
`/api/v1/voice/library-governance`	`GET`	Bearer token + projected authority context	stable
`/api/v1/workspaces/persistent`	`GET`	Bearer token + projected authority context	stable

Learning proposal governance is fail-closed: review is required before activation, self-activation is disallowed, and approved/rejected proposals are terminal (a new change requires a new proposal).

GET /api/v1/voice/library-governance is the canonical read-only governance surface for:

voice identity lifecycle state
consent expiry and re-consent triggers
re-record and re-clone triggers
brand voice pack binding
tenant/team inheritance posture
retention, deletion, and audit history references

GET /api/v1/agent-tool-policies is the canonical ACP-W3 read-only surface for:

sandbox approval posture
bounded-change scope
escalation mode and escalation target
fail-closed stale-projection action

Registration note:

there is still no shipped POST /api/v1/persistent-agents create/adopt endpoint
any future create/adopt endpoint must first pass the Spindle-backed registration validator defined in docs/SPINDLE_AGENT_REGISTRATION_REQUEST_CONTRACT.md

Auth

Inbound auth accepts:

Authorization: Bearer <token>

Self-description endpoints are open. Internal routes require a Bearer token and consume projected authority context. Exception: internal-read routes also allow the admitted agent lane without Bearer when X-JHF-Acting-Agent-Id (or X-JHF-Actor-Subject-Ref) and X-JHF-Policy-Projection-Version match Warp-owned tool-policy projection truth; missing or stale projection stays fail-closed. Internal write surfaces fail closed when the projected authority path is unavailable. Read-only routes may remain available in a clearly marked degraded mode when the projection layer is unavailable.

Deployment boundary protection is still required around all internal surfaces.

GET /metrics exports a minimal Prometheus-style text payload for service, persistence, runtime, drift, outbox, control-agent, and persistent-governance signals.

Request / Response Format

JSON over HTTP
schema contracts are defined by Pydantic models and surfaced through /openapi.json

Versioning Logic

API path version anchor: /api/v1/...
manifest schema anchor:
- fabric-manifest.json -> manifest_version
package version source:
- pyproject.toml
- src/oc_agent_manager/__init__.py
compatibility signals:
- fabric-manifest.json -> compatibility
- fabric-manifest.json -> compatibility.manifest_v2_claim_owner_projection
- fabric-manifest.json -> compatibility.agent_tool_policy_projection
- immutable OCI tags sha-<12> plus branch tag main
- Alembic migration lineage alembic/head

Example Calls

curl http://&lt;internal-runtime-redacted&gt;:8080/health
curl http://&lt;internal-runtime-redacted&gt;:8080/ready
curl http://&lt;internal-runtime-redacted&gt;:8080/version
curl -H "Authorization: Bearer $&#123;JHF_HEDDLE_ACCESS_TOKEN&#125;" http://&lt;internal-runtime-redacted&gt;:8080/metrics
curl `api/v`1/runtime/inventory
curl http://&lt;internal-runtime-redacted&gt;:8080/openapi.json

Stability Notes

self-description endpoints are intended to be stable
runtime/topology/drift endpoints are active/stable internal service contracts
MCP wrappers are not separate network API endpoints
no webhook signature standard exists yet

License

AGPLv3. See ../LICENSE (LICENSE). Learn more at helpifyr.com.

Documentation Map​

API

Scope​

Canonical Self-Description Endpoints​

Auth Boundary Classes​

Primary API Groups​

Classification and Setup​

Runtime / Topology / Drift​

Agent Federation Runtime​

Audit / Rollout​

Control Agent​

Persistent Domain Agents​

Auth​

Request / Response Format​

Versioning Logic​

Example Calls​

Stability Notes​

License​