[bbatha]

Summary

This adds the public API spec for Action Gateway endpoints and endpoint versions, and marks the legacy session routes deprecated. An endpoint is a named series of immutable versions with a live MCP URL that follows the head and a pinned URL for each version. The spec follows Tool Registry's merged REST contract, so docs and generated clients describe what the service returns.

Scope

+POST   /v2/action-gateway/endpoints
+GET    /v2/action-gateway/endpoints
+GET    /v2/action-gateway/endpoints/search
+GET    /v2/action-gateway/endpoints/{endpoint_id}
+PATCH  /v2/action-gateway/endpoints/{endpoint_id}
+DELETE /v2/action-gateway/endpoints/{endpoint_id}
+POST   /v2/action-gateway/endpoints/{endpoint_id}/versions
+GET    /v2/action-gateway/endpoints/{endpoint_id}/versions
+POST   /v2/action-gateway/endpoints/{endpoint_id}/versions:promote
+GET    /v2/action-gateway/endpoint-versions/{version_id}
+DELETE /v2/action-gateway/endpoint-versions/{version_id}

Reviewer callouts

• 🟡 Affects: public API reference, generated Python and TypeScript clients · Customers: new endpoint routes appear in the docs and SDKs; the session routes are marked deprecated and keep their current behavior.
• Insights consent belongs to the endpoint: insights is on create, PATCH, and endpoint responses. Version insights is deprecated: true; requests may send it and the service ignores it, and responses never include it.
• PATCH accepts name, insights, or both and merges insights per signal. A body with neither returns 400 endpoint_update_empty; the schema can only approximate that with minProperties: 1.
• Service-managed endpoints are hidden. Reads and writes return the same 404 as an unknown ID, and DELETE returns the same 204 and changes nothing. spectral/ruleset.yml exempts that DELETE from the required-404 rule.
• head_version uses nullable with allOf, like other schemas in this repo. The service sends null once no live version remains.