core-hub/docs/specs/api-v2-compatibility.md

API v2 Compatibility Spec

Purpose

Core Hub must preserve the Inter-Hub API surfaces that existing consumers rely on until each consumer has moved to a new explicit Core Hub contract.

Current Compatibility Semantics

The active ops-hub gate expects unauthenticated GET /api/v2/hubs to return 401, not 404 or public data. Core Hub therefore treats hub registry and bootstrap resources as protected, while keeping static catalogs and API documentation public.

The OpenAPI document served at /api/v2/openapi.json includes both FastAPI-native /api/v2/... paths and Inter-Hub-compatible unprefixed aliases such as /hubs, /hub-capability-manifests, /api-consumers, and /policy-scopes.

Public Catalog/Documentation Surfaces

• GET /api/v2/widget-types
• GET /api/v2/event-types
• GET /api/v2/annotation-categories
• GET /api/v2/policy-scopes
• GET /api/v2/openapi.json
• GET /api/v2/openapi.yaml
• GET /api/v2/docs

Protected Bootstrap Surfaces

• GET /api/v2/hubs
• POST /api/v2/hubs
• GET /api/v2/hub-capability-manifests
• POST /api/v2/hub-capability-manifests
• PATCH /api/v2/hub-capability-manifests/{manifest_id}
• POST /api/v2/hub-capability-manifests/{manifest_id}/activate
• GET /api/v2/api-consumers
• POST /api/v2/api-consumers
• POST /api/v2/api-consumers/{consumer_id}/api-keys
• GET /api/v2/widgets
• POST /api/v2/widgets
• GET /api/v2/interaction-events
• POST /api/v2/interaction-events
• GET /api/v2/hub-registry
• POST /api/v2/token

Deferred protected surfaces currently return empty compatibility collections:

• /api/v2/annotations
• /api/v2/requirement-candidates
• /api/v2/decision-records
• /api/v2/deployment-records
• /api/v2/outcome-signals

Known Consumers

• ops-hub bootstrap and Inter-Hub gate probes
• activity-core optional Inter-Hub sink
• Custodian workplans and operator smokes
• Downstream docs or probes that check the hub registry

Acceptance Standard

A route is compatible when:

• method and path match;
• auth behavior matches public/protected expectations;
• success status and response shape satisfy captured fixtures;
• error shape is documented;
• at least one consumer smoke passes against Core Hub.

Current Evidence

2026-06-27 local evidence:

• ops-hub/scripts/interhub-gate-probe.py --base http://127.0.0.1:8017 passed.
• ops-hub/scripts/ops-hub-bootstrap-api.py passed against local Core Hub with a throwaway operator token.
• The bootstrap created an ops-hub record, activated manifest, API consumer, runtime API key, 14 widgets, and one ops-endpoint-verified event.

Transition Rule

Do not remove an Inter-Hub-compatible route until every known consumer either passes against the new Core Hub-native route or has a recorded cancellation decision.