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