This page contains a log of all changes to the API and the versions that are related to each new addition.

🗂️ Versions Overview

v0.12.0-beta (Latest)

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Please review changes carefully before integrating.

🆕 What's New

• A2A support: The API now supports managing A2A specifications as table of contents entries alongside OpenAPI, AsyncAPI, GraphQL, gRPC and MCP.

  New A2aTocItem schema for A2A table of contents entries with A2aComponents grouping support for Skills, Extensions etc.
  a2a-1.0.1 value added to ApiSpecEnum enum
  A2A specifications are now indexed and searchable in published portal content
  Reference: GET Search published Portal and related endpoints

v0.11.0-beta

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Please review changes carefully before integrating.

🆕 What's New

• gRPC API support: The API now supports managing gRPC specifications as table of contents entries alongside OpenAPI, AsyncAPI, and GraphQL APIs.

  New GrpcTocItem schema for gRPC table of contents entries with grpcComponents grouping support
  New GrpcComponents schema for organizing gRPC components (Services, Messages, Enums, etc.)
  grpc value added to ApiSpecEnum enum
  gRPC specifications are now indexed and searchable in published portal content
  Reference: GET Search published Portal and related endpoints

• Portal footer simplification: Deprecated footer properties have been removed to streamline the footer content management model.

  Removed: links array, imageId, imageDarkModeId, and text fields from PortalFooter schema
  Removed: PortalFooterLink component schema (deprecated since v0.7.0-beta). The content field remains as the primary method for managing footer text (supports up to 10,000 characters)
  Reference: PATCH Patch portal and GET Get portal endpoints

• ⚠️ Removed deprecated GraphQL search fields: graphqlComponentType, graphqlComponentTitle, graphqlComponentAnchorId removed (use generic componentType, componentTitle, componentAnchorId instead)

• Landing page content management: Portal landing pages now support rich HTML/Markdown content for greater customization flexibility.

  New: landingPageContent field (supports up to 100,000 characters) replaces image-based hero and illustration approach
  Enables direct management of landing page content via the API
  Reference: PATCH Patch portal endpoint and PortalLandingPage schema

• ⚠️ Deprecated: Image-based landing page fields (heroImageAttachmentId, heroImageDarkModeAttachmentId, illustrationImageAttachmentId, illustrationImageDarkModeAttachmentId, pageDescription) are now deprecated in favor of landingPageContent
  Migration path: Use landingPageContent for rich content instead of managing separate image assets

• AsyncAPI 3.1.0 support: Added support for AsyncAPI 3.1.0 specifications alongside existing AsyncAPI 2.x and 3.0.0 versions.

  asyncapi-3.1.0 value added to ApiSpecEnum enum
  AsyncAPI 3.1.0 specifications are now supported as table of contents entries
  Reference: POST Add table of contents entry and related endpoints
   

v0.10.0-beta

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Please review changes carefully before integrating.

🆕 What's New

• Portal footer content: PATCH Patch portal and GET Get portal responses support a new free-form footer content field (up to 10,000 characters). The previous structured footer fields (links, imageId, imageDarkModeId, text) are now deprecated in favor of content and will be removed with the next API version.
• Product visibility levels: New visibility field (visible, hidden, conditional) added to product create/patch/get responses, giving finer control than the old hidden boolean, which is now deprecated (still works, but visibility takes precedence when both are set). conditional restricts display to users who already have access to the product. PATCH Patch product now returns a 409 if you try to set visibility: conditional while also making the product public. 
• Delete attachment: New DELETE Delete attachment endpoint to remove an attachment and its content. 
• Flattened/unflattened API spec downloads: New GET Download published API spec endpoint lets you download a table-of-contents entry's resolved OpenAPI/AsyncAPI spec, choosing between the flattened or unflattened version via the flattened query parameter (OAS 2.0/3.0.x only). 
  GET Published page now returns a flattened-options-available header indicating whether both options exist for that page.

v0.9.0-beta

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Please review changes carefully before integrating.

🆕 What's New

• MCP linking support: It is now possible to link MCP definition as an API and document it in Swagger Portal.
• Search Results fields deprecated: graphqlComponentType , graphqlComponentTitle, graphqlComponentAnchorId in response from GET Search published product and GET Search published Portal are deprecated and will be removed with the next API version. New fields componentType, componentTitle, componentAnchorId were added to replace them.

v0.8.0-beta

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Please review changes carefully before integrating.

🆕 What's New

• HTML document support via API
• Document source feature: Indicates if the document content is possible to manage in the Swagger Portal UI ('internal') or only via API requests ('external').
• Extension added to Search Results

v0.7.0-beta

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Please review changes carefully before integrating.

🆕 What's New

• Portal Footer feature: The API supports editing and managing Portal Footer as part of Portal Settings. To add or update footer for your Portal use PATCH Patch portal endpoint, the property is also returned in the successful response. Optional footer property was added to GET Get portals and GET Get portal endpoints responses.
• Published Content Get: Async API is now indexed for search. New optional fields corresponding to Async API 2.x.x and 3.0.0 properties were added to search results for products and portals, and the optional property asyncChannelName was removed. Request parameter q now has the length limit set to 255. 
• Published Sections Get & Template Preview Sections Get: New optional properties asyncApiMessages and asyncApiServers were added to the responses. 

v0.6.0-beta

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Please review changes carefully before integrating.

🆕 What's New

• Product Template feature: The API supports creating, editing and managing Templates. Now when you create a new product, you can do it from scratch or use a template.
• GraphQL: Creating table of contents entry's with linked GraphQL API is now supported. A new value GRAPH_QL has been added to ContentType enum.

🚨 Breaking Changes

• Published Content Get: ENDPOINTS type of search results for products and portals was renamed to OPERATION

v0.5.0-beta

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Please review changes carefully before integrating.

🆕 What's New

• HTML Content Support: The API now supports managing HtmlReference documents in addition to Markdown. This enables more flexibility in formatting and displaying portal content.
• Page Content Format: A new field pageContentFormat allows you to specify whether content is written in MARKDOWN, HTML, or BOTH.
• Product Visibility: A new boolean field hidden has been added to product metadata to control whether a product is displayed on the landing page.

🚨 Breaking Changes

• Content Reference Schema: Markdown content references are now identified as MarkdownReference instead of MarkdownDocument. If you use content linking programmatically, this may require an update to your request structure.
• Table of Contents Patch: The ability to change a table of contents entry's product via the PATCH operation has been removed.

v0.4.0-beta 

⚠️ Beta notice: This version is in beta and may introduce breaking changes. Use with caution.

🆕 What's New

No new features in this release.

🚨 Breaking Changes

• POST Create product: now requires a type property (use "type":"new").

v0.3.0-beta

⚠️ Beta notice: Use with caution; changes may not be backwards compatible.

🆕 What's New

• credentialsEnabled and routing options added to POST Create portal.
• Enum value Inter added in Patch portal.

🚨 Breaking Changes

• Add table of contents entry now requires type.
• Default openapiRenderer changed to TOGGLE in Create portal.

v0.2.0-beta

⚠️ Beta notice: Use with caution; changes may not be backwards compatible.

🆕 What's New

• Updated securitySchemes documentation for access permissions.
• slug is now optional when creating table of contents entries.
• Public OpenAPI specs are now available at /v1/openapi.json and /v1/openapi.yaml.
• openapiRenderer now allows toggling between Elements and Swagger UI.
• GET unpublished changes now includes detailed modification and a missing list.

🚨 Breaking Changes

• Only organization owners can delete products (designers no longer have access).
• PUT publish content now returns validation errors for missing/unfetchable APIs.
• Endpoints renamed:
  • POST /sections → Create section
  • POST /products → Create product

v0.1.0-beta

⚠️ Beta notice: Initial release. Expect breaking changes.

🆕 What's New

Initial launch of the SwaggerHub Portal API.

🚨 Breaking Changes

This version introduces the initial contract and is subject to future breaking changes as the API matures.