# VV_ISSUE_002 — 15 route groups lack OpenAPI specifications

**Status:** RESOLVED
**Severity:** BLOCKER
**Category:** DOCS
**Logged by:** LeadValidator
**Date:** 2026-04-07
**Audit phase:** Phase B — API Surface Audit

## Finding

The PRD (Section 6.3, Section 10.1) and README.md mandate: "Every API endpoint MUST have an
OpenAPI 3.0 specification BEFORE implementation begins. No exceptions."

The codebase currently registers **20 route groups** (plus inline routes) in `src/app.ts`.
Only **5 OpenAPI specs** exist in `docs/openapi/`. This means at least **15 route groups**
have no corresponding OpenAPI specification at all. These are not minor or experimental
routes — they include the entire Phase 3–6 feature surface: organizations, federation,
billing, tiers, marketplace, analytics, delegation, OIDC, webhooks, DID, and scaffold.

This is not a post-hoc documentation gap. The PRD requires the spec to exist **before**
implementation. These features were shipped without specs, which means:
1. The API contract was never formally reviewed or approved
2. There is no authoritative reference for what these endpoints do
3. Integration with external consumers (SDKs, field trial runbook) relies on undocumented behavior

## Evidence

**OpenAPI specs that exist** (`docs/openapi/`):
- `agent-registry.yaml` — covers `/api/v1/agents`
- `audit-log.yaml` — covers `/api/v1/audit`
- `compliance.yaml` — covers `/api/v1/compliance`
- `credential-management.yaml` — covers `/api/v1/agents/:agentId/credentials`
- `oauth2-token.yaml` — covers `/api/v1/token`

**Route groups registered in `src/app.ts` with NO OpenAPI spec:**

| Route prefix | Router function | File |
|---|---|---|
| `/health` | `createHealthRouter` | `src/routes/health.ts` |
| `/metrics` | `createMetricsRouter` | `src/routes/metrics.ts` |
| `/.well-known/did.json` | inline `didController.getInstanceDIDDocument` | `src/app.ts:329` |
| `/` (OIDC well-known) | `createOIDCRouter` | `src/routes/oidc.ts` |
| `/api/v1` (DID) | `createDIDRouter` | `src/routes/did.ts` |
| `/api/v1/organizations` | `createOrgsRouter` | `src/routes/organizations.ts` |
| `/api/v1` (federation) | `createFederationRouter` | `src/routes/federation.ts` |
| `/api/v1/webhooks` | `createWebhooksRouter` | `src/routes/webhooks.ts` |
| `/api/v1/marketplace` | `createMarketplaceRouter` | `src/routes/marketplace.ts` |
| `/api/v1/billing` | `createBillingRouter` | `src/routes/billing.ts` |
| `/api/v1/tiers` | `createTiersRouter` | `src/routes/tiers.ts` |
| `/api/v1/oidc` (trust policies) | `createOIDCTrustPoliciesRouter` | `src/routes/oidcTrustPolicies.ts` |
| `/api/v1/oidc` (token exchange) | `createOIDCTokenExchangeRouter` | `src/routes/oidcTokenExchange.ts` |
| `/api/v1` (delegation) | `createDelegationRouter` | `src/routes/delegation.ts` |
| `/api/v1/analytics` | `createAnalyticsRouter` | `src/routes/analytics.ts` |
| `/api/v1` (scaffold) | `createScaffoldRouter` | `src/routes/scaffold.ts` |

## Required Action

Create an OpenAPI 3.0 specification for every route group listed above. Each spec must cover:
- All endpoints (path, method)
- Request body schemas with validation rules
- Response schemas for all status codes (2xx, 4xx, 5xx)
- Authentication requirements (Bearer token, scopes)
- Example requests and responses

Recommended approach: create one YAML file per route group in `docs/openapi/`, matching the
pattern of the existing 5 specs.

This is a BLOCKER. No production release is permitted while this finding is OPEN.

## CTO Response

All 15 required OpenAPI 3.0 specification files have been created in `docs/openapi/`.
Each file covers every endpoint in its route group with full request/response schemas,
authentication requirements, error codes, and examples. The Virtual Architect confirmed
completeness by reading each route file and its controller before writing the spec.

## Resolution

**Status updated to RESOLVED — 2026-04-07**

All 15 OpenAPI 3.0 YAML files now exist in `docs/openapi/`:

| Route group | Spec file | Endpoints |
|---|---|---|
| `/health` | `health.yaml` | 2 (GET /health, GET /health/detailed) |
| `/metrics` | `metrics.yaml` | 1 (GET /metrics) |
| `/.well-known/did.json` + DID routes | `did.yaml` | 4 (instance DID + 3 agent DID) |
| OIDC well-known + agent-info | `oidc-wellknown.yaml` | 3 (discovery, JWKS, agent-info) |
| `/api/v1/organizations` | `organizations.yaml` | 6 (CRUD + members) |
| `/api/v1/federation` | `federation.yaml` | 6 (partners CRUD + verify) |
| `/api/v1/webhooks` | `webhooks.yaml` | 6 (subscriptions CRUD + deliveries) |
| `/api/v1/marketplace` | `marketplace.yaml` | 2 (list + detail) |
| `/api/v1/billing` | `billing.yaml` | 3 (checkout, webhook, usage) |
| `/api/v1/tiers` | `tiers.yaml` | 2 (status + upgrade) |
| `/api/v1/oidc/trust-policies` | `oidc-trust-policies.yaml` | 3 (create, list, delete) |
| `/api/v1/oidc/token` | `oidc-token-exchange.yaml` | 1 (exchange) |
| `/api/v1/oauth2/token/delegate` | `delegation.yaml` | 3 (create, verify, revoke) |
| `/api/v1/analytics` | `analytics.yaml` | 3 (tokens, activity, agents) |
| `/api/v1/sdk/scaffold` | `scaffold.yaml` | 1 (GET scaffold ZIP) |

Every spec conforms to OpenAPI 3.0.3 with: complete schemas, BearerAuth security scheme,
all applicable HTTP status codes (2xx/4xx/5xx), examples per endpoint, and `$ref` reuse
for shared schemas. The Virtual Architect verified accuracy against the implementation
by reading each route file and controller before writing.