registry OpenAPI: define community-mirror lifecycle endpoints (/api/registry/mirrors) + schemas so SDKs can generate types

[bokelley]

Summary

The registry service implements a community-mirror lifecycle (publish / get / list persisted adagents mirrors keyed by platform), but those endpoints and their schemas are not defined in the registry OpenAPI spec (static/openapi/registry.yaml, served at https://agenticadvertising.org/openapi/registry.yaml). As a result, every SDK has to hand-roll the DTOs instead of generating typed models from the spec.

Evidence

• The spec (live, ~8967 lines) has no /api/registry/mirrors path and no CommunityMirror* schema — the only "mirror" hits are incidental prose. The concept is mentioned in the POST /api/adagents/create description ("…authorized_agents may be empty for a catalog-only community mirror…") but the persisted lifecycle is undocumented.
• JS SDK added a client for these endpoints with hand-written TS DTOs (not generated): adcontextprotocol/adcp-client#2183 (lifecycle client) and #2187 (upsert helper) — CommunityMirrorAdagentsCatalog, PublishCommunityMirrorAdagentsResponse, ListCommunityMirrorAdagentsResponse, CommunityMirrorAdagentsConfig.
• Python SDK hit the same wall: adcontextprotocol/adcp-client-python#925 / PR #929 currently type these as dict[str, Any] because there is no generated model in adcp.types.registry to use.

Because both SDKs generate registry types from this OpenAPI spec, the missing definitions force divergent, reverse-engineered DTOs per language — exactly what the spec-as-source-of-truth model is meant to prevent.

Endpoints to define (shapes from the JS implementation — please confirm against the service)

• PUT /api/registry/mirrors/{platform} — publish a community-mirror adagents catalog. Auth required. Body is the built catalog (authorized_agents: [], catalog_etag, formats, optional properties, superseded_by). platform normalized to ^[a-z0-9_-]{1,64}$; each properties[].platform must normalize to the route platform.
• GET /api/registry/mirrors/{platform} — fetch one; 404 when absent. Response wrapper: { platform, superseded_by, adagents_json }.
• GET /api/registry/mirrors — list with optional limit / offset; response { mirrors: [...], total }.

Schemas to define

CommunityMirrorAdagentsCatalog, the publish response, the get-wrapper, the list response, and the publish/upsert input config.

Secondary (optional, same family)

POST /api/adagents/create is also untyped in the Python client (dict[str, Any]) — its request/response are likewise not modeled. Worth defining its response schema while this area is being touched, so the whole adagents/mirror family is generated rather than hand-rolled.

Why this matters

Spec is the source of truth; the SDKs run datamodel-code-generator against it. Undefined endpoints → hand-written DTOs that drift from the service and from each other across JS/Python/Go. Adding these to static/openapi/registry.yaml lets every SDK generate real types and delete the stopgap dicts.

Cross-references

• JS: adcontextprotocol/adcp-client#2183, #2187
• Python: adcontextprotocol/adcp-client-python#925, #929

(Surfaced while wiring registry community-mirror parity into the Python SDK. The exact request/response shapes above are reverse-engineered from the JS client and should be validated against the registry service implementation before being committed to the spec.)

[bokelley]

Triage

Classification: Feature request (spec gap — documenting live endpoints)
Bucket(s): registry / discovery, schema (OpenAPI codegen)
Status: ready-to-implement
Milestone: Evergreen

What the experts said:

• ad-tech-protocol-expert: Additive and non-breaking. Two naming issues before commit: (1) superseded_by needs a declared type + normative re-fetch rule, otherwise codegen produces any everywhere; (2) adagents_json as a top-level GET-response field collides with an existing spec enum value — use catalog or adagents_catalog_json instead. PUT semantics and platform regex are fine. Schemas belong in components/schemas as named $refs.
• adtech-product-expert: Service is already fully live (routes at server/src/routes/community-mirrors.ts, DB at server/src/db/community-mirror-db.ts, migrations shipped). The issue's reverse-engineered shapes are incomplete: the DELETE /api/registry/mirrors/{platform} endpoint and the publisher_domains: string[] field on the PUT response are absent. Read the service source before writing YAML. No WG review needed — this is an operator API, not inter-party protocol. Experts split on changeset: protocol expert says minor (additive to published spec); product expert says --empty (documenting live behavior). Confirm intent with @bokelley before opening the PR.

My take: The gap is real and actively blocking codegen in two SDKs. This is a transcription task — read the live service types, then write YAML — but the issue body is incomplete; use the service source as ground truth, not the issue shapes.

Implementation scope:

• Read first: server/src/routes/community-mirrors.ts (MirrorBodySchema ~L33-63, response shapes ~L117, 135-141, 234-241, 286) and server/src/db/community-mirror-db.ts (CommunityMirrorSummary vs CommunityMirror interfaces).
• Paths to add in static/openapi/registry.yaml:
  • GET /api/registry/mirrors — public, paginated (limit/offset), returns { mirrors: CommunityMirrorSummary[], total: integer } (summary omits adagents_json and audit fields)
  • GET /api/registry/mirrors/{platform} — public, full object; 404 on miss
  • PUT /api/registry/mirrors/{platform} — auth required; body from MirrorBodySchema; response must include publisher_domains: string[]
  • DELETE /api/registry/mirrors/{platform} — auth required; ?force=true query param; 409 when no superseded_by and force not set (this endpoint was missing from the issue)
• Schema notes: Avoid adagents_json as a field name in the GET response wrapper; define superseded_by type (slug vs. URL) and document whether callers should re-fetch the chain.
• Secondary (same PR): Tighten POST /api/adagents/create response — adagents_json: {} and validation: {} are currently untyped; add validation: { valid: boolean, errors: string[] } and a concrete adagents_json type.
• PR title form: docs(openapi): add community-mirror lifecycle endpoints and tighten adagents/create response schema

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01UJm944RhLPQJUYdY2Esm2p

---

Generated by Claude Code

[bokelley]

Resolved by #5385 (merged) — the community-mirror lifecycle endpoints (GET list, GET one, PUT publish, DELETE) and their schemas are now in static/openapi/registry.yaml, plus CreateAdagentsResponse for /api/adagents/create. The Python SDK has already regenerated typed models from the merged spec and retyped its client (adcontextprotocol/adcp-client-python#929), replacing the dict[str, Any] stopgaps.