
The Swagger Portal client provides comprehensive portal and product management capabilities. Access to these features requires authentication with a `SWAGGER_API_KEY`.
## Available Tools
### Portal Management Tools
#### `list_portals`
- Purpose: Search for available portals within Swagger. Returns only the portals for which you are an owner or designer, either at the product or organization level.
- Returns: Paginated list of portals, including metadata such as name, subdomain, status, and more.
- Use case: Discovery of available portals.
#### `get_portal`
- Purpose: Retrieve information about a specific portal.
- Parameters: Portal UUID or subdomain (`portalId`).
- Returns: Complete set of metadata properties for a specific portal.
- Use case: Get full details on a specific portal configuration.
#### `create_portal`
- Purpose: Create a new portal with Swagger.
- Returns: Complete set of metadata properties for a specific portal.
- Use case: Get full details on a specific portal configuration.
- Parameters:
| Parameter | Description | Type | Required |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- |
| `name` | The portal name.
Must be between 3 and 40 characters. | string | No |
| `subdomain` | The subdomain to use for the portal.
Must be between 3 and 20 characters. | string | Yes |
| `offline` | If set to true the portal will not be visible to customers.
Default: `false` | boolean | No |
| `routing` | Determines the routing strategy ('`browser`' or '`proxy`').
Default: `browser` | string | No |
| `credentialsEnabled` | Indicates if credentials are enabled for the portal.
Default: `true` | boolean | No |
| `swaggerHubOrganizationId` | The corresponding Swagger (formerly SwaggerHub) organization UUID | string (uuid) | Yes |
| `openapiRenderer` | Portal level setting for the OpenAPI renderer.
- `SWAGGER_UI` - Use the Swagger UI renderer
- `ELEMENTS` - Use the Elements renderer
- `TOGGLE` - Switch between the two renderers with elements set as the default
Default: `TOGGLE` | string | No |
| `pageContentFormat` | Determines the format of the page content (`HTML` or `MARKDOWN` or `BOTH`)
Default: `HTML` | string | No |
#### `update_portal`
- Purpose: Update a specific portal's configuration.
- Returns: Complete set of metadata properties for a specific portal.
- Use case: Update configuration settings of existing Swagger portal.
- Parameters:
| Parameter | Description | Type | Required |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| `portalId` | Portal UUID or subdomain - unique identifier for the portal instance | string | Yes |
| `name` | Update the portal display name - shown to users and in branding (3-40 characters) | string | No |
| `subdomain` | Update the portal subdomain - changes the portal URL. Must remain unique across all portals (3-20 characters, lowercase, alphanumeric with hyphens) | string | No |
| `customDomain` | Set a custom domain for the portal by providing the domain name as a string. To remove the custom domain, set this value to `null`. | string | No |
| `offline` | Set portal visibility - true hides portal from customers (useful for maintenance or development) | boolean | No |
| `gtmKey` | Google Tag Manager key for analytics tracking - format: GTM-XXXXXX (max 25 characters) | string | No |
| `routing` | Update routing strategy - 'browser' for client-side routing or 'proxy' for server-side routing | string | No |
| `credentialsEnabled` | Enable/disable authentication credentials for portal access - controls whether users can authenticate to view private content | boolean | No |
| `openapiRenderer` | Change OpenAPI renderer: 'SWAGGER_UI' (Swagger UI), 'ELEMENTS' (Stoplight Elements), or 'TOGGLE' (switch between both) | string | No |
| `pageContentFormat` | Update page content format for documentation rendering: 'HTML', 'MARKDOWN', or 'BOTH' | string | No |
#### `resolve_organization_portal`
- Purpose: Resolve portal details for a Swagger organization in a single step. Finds the portal mapped to the given organization and returns its details along with the portal's products. If the organization has no portal yet, a new portal is created automatically (with a subdomain derived from the organization name).
- Returns: The organization ID, portal ID, subdomain, `customDomain` (only when the portal has one configured), a `portalCreated` flag indicating whether a new portal was created, and the list of products (`productId`, `productSlug`, `productName`).
- Use case: Obtain all portal context needed for subsequent portal and product operations without performing multiple manual lookup steps.
- Parameters:
| Parameter | Description | Type | Required |
| ---------------- | ------------------------------------------------------------------ | ------------- | -------- |
| `organizationId` | Swagger organization UUID to resolve portal details for | string (uuid) | Yes |
#### `list_portal_products`
- Purpose: Get products for a specific portal.
- Parameters: Portal UUID or subdomain (`portalId`).
- Returns: Paginated list of products in a portal.
- Use case: Understanding the products that exist for a given portal.
#### `get_portal_product`
- Purpose: Retrieve information about a specific product resource.
- Parameters: Product UUID (`productId`).
- Returns: Complete set of properties for a specific product.
- Use case: Understanding the product information and status (both from a publishing and visibility perspective).
#### `create_portal_product`
- Purpose: Create a new product within a specific portal.
- Returns: Information about the newly created product.
- Use case: Add a new product to a portal.
- Parameters:
| Parameter | Description | Type | Required |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------- |
| `portalId` | Portal UUID or subdomain. | string | Yes |
| `type` | Product creation type - 'new' to create from scratch or 'copy' to duplicate an existing product | string | Yes |
| `sourceProductId` | Source product UUID to copy from when type is 'copy'. Specifies which existing product to duplicate. Omit when type is 'new'. | string | No |
| `name` | Product display name - will be shown to users in the portal navigation and product listings (3-40 characters) | string | Yes |
| `slug` | URL-friendly identifier for the product - must be unique within the portal, used in URLs (e.g., 'my-api' becomes /my-api). 3-22 characters, lowercase, alphanumeric with hyphens, underscores, or dots | string | Yes |
| `description` | Product description - explains what the API/product does, shown in product listings and cards (max 110 characters) | string | No |
| `public` | Whether the product is publicly visible to all portal visitors - false means only authenticated users with appropriate roles can access it | boolean | No |
| `hidden` | Whether the product is hidden from the portal landing page navigation menus - useful for internal or draft products | boolean | No |
| `role` | Whether the product has role-based access restrictions - controls if specific user roles are required to access the product | boolean | No |
#### `update_portal_product`
- Purpose: Update an product within a specific portal.
- Returns: Information about the updated product, including all product properties and an optional `url` field with the portal URL for the product (null if URL generation fails).
- Use case: Change information on an existing product.
- Parameters:
| Parameter | Description | Type | Required |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| `productId` | Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product | string | Yes |
| `name` | Update product display name - changes how it appears to users in navigation and listings (3-40 characters) | string | No |
| `slug` | Update URL-friendly identifier - must remain unique within the portal, affects product URLs (3-22 characters, lowercase, alphanumeric with hyphens/underscores/dots) | string | No |
| `description` | Update product description - explains the API/product functionality, shown in listings (max 110 characters) | string | No |
| `public` | Change product visibility - true makes it publicly accessible to all visitors, false restricts to authenticated users with roles | boolean | No |
| `hidden` | Change navigation visibility - true hides from portal landing page menus while keeping the product accessible via direct links | boolean | No |
#### `delete_portal_product`
- Purpose: Delete a product from a specific portal.
- Parameters: Product UUID (`productId`).
- Returns: No content on success.
- Use case: Delete an existing product from a Swagger portal.
#### `publish_portal_product`
- Purpose: Publish a product's content to make it live or as a preview. This endpoint publishes the current content of a product, making it visible to portal visitors.
- Use: Call with `preview` set to `true` for preview publishes, `false` for live. Optionally pass `tableOfContentsId` to resolve a page-specific URL.
- Returns:
- `success` (boolean)
- `preview` (boolean)
- `liveUrl` (string|null) — present when `preview` is false and URL build succeeds; otherwise `null`
- `previewUrl` (string|null) — present when `preview` is true and URL build succeeds; otherwise `null`
- `product` (object) — `{ id, name, slug }` when available
- `portal` (object) — `{ id, name, subdomain, customDomain }` when available
- `tableOfContentsItem` (object|null) — present when `tableOfContentsId` resolved
- `warning` (object) — returned when metadata/URL building failed; contains `code`, `step`, and `message`. A `warning` does NOT mean the publish failed.
- Parameters:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| `productId` | Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product | string | Yes |
| `preview` | Whether to publish as preview (true) or live (false). Preview allows testing before going live. Defaults to false (live publication) | boolean | No |
| `tableOfContentsId` | Optional table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug' used to resolve a specific live URL path | string | No |
**Response Details:**
- Returns success plus product/portal metadata and a publish URL (previewUrl if preview, else liveUrl); includes tableOfContentsItem (and a direct TOC URL) only when tableOfContentsId was provided and resolved.
- When URL building fails, response includes `liveUrl`/`previewUrl` as `null` and a `warning` explaining the failure.
### Product Sections Management
#### `list_portal_product_sections`
- Purpose: Get sections for a specific product within a portal.
- Returns: List of sections within a product, including metadata and embedded table of contents if requested.
- Use case: Understanding the structure and organization of content within a product.
- Parameters:
| Parameter | Description | Type | Required |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| `productId` | Product UUID or identifier in the format 'portal-subdomain:product-slug' - unique identifier for the product | string | Yes |
| `embed` | List of related entities to embed in the response - e.g., ['tableOfContents', 'tableOfContents.swaggerhubApi'] to include table of contents and SwaggerHub API details | array | No |
| `page` | Page number for paginated results - specifies which page of results to retrieve (default is 1) | number | No |
| `size` | Number of items per page for pagination - controls how many results are returned per page (default is 20) | number | No |
### Table of Contents Management
#### `create_table_of_contents`
- Purpose: Create a new table of contents item in a portal product section. Supports API references, HTML content, and Markdown content types.
- Returns: Information about the newly created table of contents item.
- Use case: Add structured content navigation to product sections.
- Parameters:
| Parameter | Description | Type | Required |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------- |
| `sectionId` | Section ID - unique identifier for the section within the product | string | Yes |
| `type` | Type of table of contents creation - 'new' to create from scratch or 'copy' to duplicate an existing one | string | Yes |
| `title` | Title of the table of contents item - will be displayed in navigation (3-40 characters) | string | Yes |
| `slug` | URL-friendly identifier for the table of contents item - must be unique within the section (3-22 characters, lowercase, alphanumeric with hyphens/underscores/dots) | string | Yes |
| `order` | Order position of the table of contents item within its parent section or item | number | Yes |
| `parentId` | Parent table of contents item ID - null for top-level items, or ID of parent item for nested structure | string/null | No |
| `content` | Content configuration for the table of contents item | object | Yes |
#### `list_table_of_contents`
- Purpose: Get table of contents for a section of a product within a portal.
- Returns: List of table of contents items within a section, including nested structure and content metadata.
- Use case: Understanding the navigation structure and content organization within a product section.
- Parameters:
| Parameter | Description | Type | Required |
| ----------- | ------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| `sectionId` | Section ID - unique identifier for the section within the product | string | Yes |
| `embed` | List of related entities to embed in the response - e.g., ['swaggerhubApi'] to include SwaggerHub API details | array | No |
| `page` | Page number for paginated results - specifies which page of results to retrieve (default is 1) | number | No |
| `size` | Number of items per page for pagination - controls how many results are returned per page (default is 20) | number | No |
#### `delete_table_of_contents`
- Purpose: Delete table of contents entry. Performs a soft-delete of an entry from the table of contents. Supports recursive deletion of nested items.
- Returns: No content on success.
- Use case: Remove table of contents items and optionally their nested structure.
- Parameters:
| Parameter | Description | Type | Required |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| `tableOfContentsId` | The table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug' | string | Yes |
| `recursive` | Flag to include all the nested tables of contents (default: false) | boolean | No |
### Document Management
**Note**: Documents are managed as part of table of contents items. To delete a document, use `delete_table_of_contents` which will remove the table of contents entry and any associated document content.
#### `create_documentation_page`
- Purpose: Create a documentation page in a portal product in a single tool call. Supports markdown and html content types. Shortcut for adding a new table of contents page to a portal product without managing sections or table of contents separately.
- Returns: Page location details (`productId`, `sectionId`, `sectionSlug`, `pageDetails`) and a `draftUrl` to edit the page in the portal admin.
- Use case: Quickly add a new documentation page to an existing product.
- Parameters:
| Parameter | Description | Type | Required |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------- | -------- |
| `portalId` | Portal UUID or subdomain - unique identifier for the portal | string | Yes |
| `productId` | Product UUID - unique identifier for the product | string | Yes |
| `pageTitle` | Title of the documentation page - displayed in navigation (3-255 characters) | string | Yes |
| `pageContent` | Content of the documentation page. Provide HTML when `contentType` is `html`, Markdown when `contentType` is `markdown` | string | No |
| `pageSlug` | URL slug for the page - 3-255 characters, lowercase, alphanumeric with hyphens, underscores, or dots (e.g. `my-page`). If not provided, the slug is generated from the page title. | string | No |
| `contentType` | Content type of the page: `markdown` (default) or `html`. | string | No |
| `source` | Where content is managed: `internal` (default, editable in portal UI and API) or `external` (API only). | string | No |
| `order` | Order position of the page within its parent section or item (default: 0) | number | No |
| `parentId` | Parent table of contents item ID - null for top-level pages, or ID of parent item for nested structure (default: null) | string/null | No |
**Note:** `html` + `internal` is not supported — creating a page with content with this combination via MCP or API will return an error.
#### `get_document`
- Purpose: Get document content and metadata by document ID. Useful for retrieving HTML or Markdown content from table of contents items.
- Returns: Document content and metadata including type, creation/modification dates.
- Use case: Retrieve content for editing or display purposes.
- Parameters:
| Parameter | Description | Type | Required |
| ------------ | -------------------------------------------------- | ------ | -------- |
| `documentId` | Document UUID - unique identifier for the document | string | Yes |
#### `update_document`
- Purpose: Update the content or source of an existing document. Supports HTML and Markdown content types.
- Returns: Updated document metadata.
- Use case: Modify existing documentation content within portal products.
- Parameters:
| Parameter | Description | Type | Required |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- |
| `documentId` | Document UUID - unique identifier for the document | string | Yes |
| `content` | The document content to update (HTML or Markdown based on document type) | string | No |
| `type` | Content type: `html` or `markdown`. Note: `html` + `internal` documents cannot be edited via API. | string | No |
| `source` | Where content is managed: `internal` (editable in portal UI and API) or `external` (API only). Note: `html` + `internal` cannot be updated via API. | string | No |
## Configuration
To use Swagger Portal tools, you need to configure the `SWAGGER_API_KEY` environment variable with your Swagger API token.
## Common Use Cases
1. **Portal Discovery**: Use `list_portals` to find available portals you have access to.
2. **Portal Management**: Create and update portals using the respective tools.
3. **Product Organization**: Manage products within portals for better API organization.
4. **Content Publishing**: Use `publish_portal_product` to make product content live or preview changes before publishing.
5. **Content Structure Management**: Organize product content using sections and table of contents for better navigation.
6. **Document Management**: Create, update, and manage documentation content within portal products.
7. **Portal Content Architecture**: Build comprehensive documentation portals with nested content structures and API references.