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.

Initial Compatibility Surface

Public/read surfaces:

• GET /api/v2/hubs
• GET /api/v2/hub-capability-manifests
• 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/write or authenticated surfaces:

• POST /api/v2/token
• /api/v2/api-consumers
• /api/v2/widgets
• /api/v2/interaction-events
• /api/v2/annotations
• /api/v2/requirement-candidates
• /api/v2/decision-records
• /api/v2/deployment-records
• /api/v2/outcome-signals
• /api/v2/hub-registry

Potentially preserved SDK endpoints:

• /api/v2/sdk
• /api/v2/sdk/ihf-client.ts
• /api/v2/sdk/ihf-client.py

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 public 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.

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.