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