Initially, all added documents and APIs are visible only on the designer side of the Portal. To make them accessible to your consumers, an additional action is required.
💡 Resolved State
The APIs linked in products are in an unresolved state. The API is in a resolved state after a Preview or Publish action. A resolved state means that the APIs also show:
Contents of external references, if there are external references in the API.
Domains information, if domains are referenced in the API in SwaggerHub.
Get unpublished changes
Before publishing the content, it is advisable to review the changes that will be visible to consumers. To accomplish this, use the GET Unpublished changes endpoint. The response will provide a list of all entries that have been added since the product's creation or modified since the last publication, as well as existing comments and suggestions that will be omitted in the publishing process if not accepted before.
Sample Request
curl -X GET "https://api.portal.swaggerhub.com/v1/products/<PRODUCT-ID>/published-content/changes" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"Sample Response
{
"added": [
{
"path": "petstore/api",
"tableOfContentsId": "f91f8be2-ccbc-483a-93a7-a692763f79a5",
"title": "New API Endpoint",
"type": "apiUrl"
}
],
"modified": [
{
"path": "petstore/getting-started",
"tableOfContentsId": "f91f8be2-ccbc-483a-93a7-a692763f79a5",
"title": "Updated Getting Started Guide",
"type": "markdown",
"modifications": [
{
"type": "TITLE_CHANGED"
}
]
}
],
"removed": [
{
"path": "petstore/old-endpoint",
"tableOfContentsId": "f91f8be2-ccbc-483a-93a7-a692763f79a5",
"title": "Deprecated API Endpoint",
"type": "apiUrl"
}
],
"missing": [
{
"path": "petstore/missing-api",
"tableOfContentsId": "f91f8be2-ccbc-483a-93a7-a692763f79a5",
"title": "Missing API",
"type": "apiUrl"
}
],
"reordered": true,
"comments": [
{
"path": "petstore/api",
"tableOfContentsId": "f91f8be2-ccbc-483a-93a7-a692763f79a5",
"title": "Comment on New API Endpoint"
}
]
}🚧 Important: You cannot publish if any of your APIs are un-resolvable or are missing.
Possible causes if any of your APIs are un-resolvable:
- Provider doesn't have correct permissions to access external references
- API validation issues related to references
If any of your APIs appears as missing, it means it is inaccessible in Swagger Studio and must be unlinked to preview or publish the product. Possible causes:
- API renamed in Swagger Studio
- API deleted from Swagger Studio
- Provider doesn't have correct permissions to the API
- Anything that affects the API URL structure
Publish content
Use the PUT Publish product endpoint to publish changes made to the product.
Sample Request
curl -X PUT "https://api.portal.swaggerhub.com/v1/products/<PRODUCT-ID>/published-content" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"In case of a processing error, the response with validation message is returned providing information of the error type and ID of each table-of-contents entry that caused the issue.
Sample Response
{
"validationMessages": [
{
"level": "error",
"message": "The product failed to publish due to errors.",
"errorCode": "INVALID_API",
"tableOfContentsId": "f91f8be2-ccbc-483a-93a7-a692763f79a5"
}
]
}Possible error types and their explanation:
| Error Code | Detail |
|---|---|
| NOT_FOUND | The requested resource was not found. |
| AUTH_FAILURE | Access token not set or invalid. The requested resource could not be returned. |
| INVALID_URL | Syntax of URL is invalid. |
| URL_NOT_ALLOWED | URL is not allowed for security reasons. |
| INVALID_API | API is not a valid OpenAPI, AsyncAPI or GraphQL. |
| YAML_JSON_INVALID | Invalid YAML or JSON format. |
| PARSE_ERROR | Error while parsing (Swagger/OpenAPI parser message). |
| CANT_PROCESS_SCHEMA | Error while processing GraphQL schema. |
| UNKNOWN | All other errors. |
Preview product
To preview the content of a specific product before actually publishing, you can use PUT Publish product endpoint with preview query parameter value set to true.
Sample Request
curl -X PUT "https://api.portal.swaggerhub.com/v1/products/<PRODUCT-ID>/published-content?preview=true" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"Then use GET Published sections endpoint to check which table-of-contents entries were affected and GET Published page to review content that would be published under the specific path. Both endpoints require preview=true parameter to return data of generated preview. If the value is not specified, endpoints will return last published content by default.
Get Published Sections
Sample Request
curl -X GET "https://api.portal.swaggerhub.com/v1/products/<PRODUCT-ID>/published-content/sections?preview=true" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"Sample Response
{
"page": {
"number": 1,
"size": 10,
"totalElements": 1,
"totalPages": 1
},
"items": [
{
"title": "Getting Started",
"slug": "getting-started",
"tableOfContents": [
{
"tableOfContentsId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sourceTemplateTocId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "markdown",
"title": "Getting Started",
"path": "doc/getting-started",
"children": []
}
]
}
]
}Get Published Page
Sample Request
curl -X GET "https://api.portal.swaggerhub.com/v1/products/<PRODUCT-ID>/published-content/page?preview=true&path=docs/getting-started" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"📝 Note:
pathparameter value is required. You can copy its value from GET Published section response or combine section's and table-of-contents' slugs📝 Note: The response body is the raw page content itself (not wrapped in JSON) — its Content-Type matches the page's format (e.g. text/html). Metadata is returned as response headers, not body fields:
content-type,last-modified, andflattened-options-availableare HTTP response headers, not JSON fields — the response body is the raw page content itself, and its shape/type depends on the page (HTML shown here; a linked OpenAPI/AsyncAPI page returns YAML/JSON instead).flattened-options-availableistrueonly for OAS 2.0/OAS 3.0.x pages published for AsyncAPI, GraphQL, MCP, and OAS 3.1+ pages it's alwaysfalse.
Sample Response
HTTP/1.1 200 OK
content-type: text/html
last-modified: 2023-10-01T12:00:00Z
flattened-options-available: true
<h1>Getting Started</h1>
<p>Welcome to the API documentation. This guide will help you get started with our API.</p>
Download Published API Spec
To download the underlying OpenAPI or AsyncAPI spec for a specific table-of-contents entry, use the GET Download published API spec endpoint. GraphQL and MCP entries are not supported and return a 400.
Sample Request
curl -X GET "https://api.portal.swaggerhub.com/v1/products/<PRODUCT-ID>/published-content/api-spec?tocId=<TOC-ID>&flattened=true&format=yaml" \
-H "Authorization: Bearer YOUR_API_KEY"Sample Response
HTTP/1.1 200 OK
content-type: application/json
{
"openapi": "3.0.3",
"info": {
"title": "Pets and Adoptions API",
"version": "1.0.0"
},
"paths": { ... }
}
📝 Note:
content-typereflects the requested format (application/yaml or application/json) — there are no other custom response headers on this endpoint. Unlike Get Published Page, the body here is always the resolved spec document itself.