Docs / Comparisons
CHP vs APIs
APIs center endpoints and services. CHP centers hosted capabilities with lifecycle, policy, invocation, outcomes, and evidence.
Plain English
CHP can sit beside APIs, but it explains what an ability means and how it is governed before it is called.
Why it exists
An endpoint shape alone does not tell an agent whether a capability is available, authorized, compatible, or auditable.
Formal definition
CHP is a capability protocol layer over or beside APIs that standardizes manifest discovery, invocation safety, structured outcomes, and evidence semantics.
Concrete example
Ground the concept before the schema.
POST /dispatch may exist as an API endpoint; schedule_technician is the CHP capability contract independent callers can reason about.
Finds an available qualified technician and reserves a service window.
{ "id": "service-ops-host", "version": "0.1.0", "protocol_version": "0.1", "kind": "service", "capabilities": [{ "id": "schedule_technician", "version": "1.0.0", "description": "Finds an available qualified technician and reserves a service window.", "status": "experimental", "modes": ["sync"], "emits": ["execution_started", "execution_completed", "execution_denied"], "policy": { "risk_tier": "high", "auth_required": true, "approval_required": true, "allowed_actors": ["agent://planning-assistant"] }, "metadata": { "required_permissions": ["service:dispatch"], "lifecycle": "invokable" } }], "evidence": { "store": "local-append-only", "append_only": true }}Category contrast
CHP vs APIs: what changes
CHP can complement adjacent systems, but it centers a different protocol boundary.
Compared to
APIs
They center
Endpoints, resources, methods, and transport schemas.
CHP centers
Hosted capabilities, lifecycle, policy, structured outcomes, evidence, and conformance.
Use APIs to implement services.
Use CHP to expose governed capability contracts to independent callers.
Use adapters when existing APIs need CHP semantics.
Relationships
Where this sits in the protocol.
Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.
APIs can back CHP adapters or hosts.
CHP manifests can point to capabilities implemented by HTTP services.
OpenAPI remains useful for transport and schema details.
Visual model
- 01API endpoint exposes transport.
- 02CHP capability exposes operational meaning.
- 03Host enforces policy and emits evidence.
Implementation notes
- Keep HTTP implementation details behind the capability boundary.
- Map HTTP errors into structured CHP outcomes.
- Use OpenAPI where it helps describe transport schemas.
Common mistakes
- Renaming endpoints as capabilities without adding lifecycle or policy.
- Letting HTTP status codes carry all protocol meaning.
- Assuming API authentication is enough for capability governance.
Related concepts