It's very natural to want to manage an existing API product. The administrative APIs support editing the product settings, as well as the ability to add, edit, or delete API references and documentation pages. Should the need arise to delete a product completely, the APIs also cater for this use case.
Edit Product Settings
Use the PATCH Patch product endpoint to update product settings.
curl --location --request PATCH 'https://api.portal.swaggerhub.com/v1/products/<PRODUCT-ID>' \
--header 'Authorization: Bearer <YOUR-SWAGGER-APIKEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "Pet Adoptions",
"slug": "pet-adoptions",
"description": "API documentation, tutorials, and guides enabling programmatic adoption of pets",
"public": true,
"visibility": "visible"
}'❗ Note: Setting
visibility: conditionaltogether withpublic: truereturns a 409, since a public product can't also be conditionally restricted.
Edit API Reference, Documentation, or Table of Contents Order
Use the PATCH Patch table of contents entry endpoint to modify existing entries.
curl --location --request PATCH 'https://api.portal.swaggerhub.com/v1/table-of-contents/<ID>' \
--header 'Authorization: Bearer <YOUR-SWAGGER-APIKEY>' \
--header 'Content-Type: application/json' \
--data '{
"slug": "pets-and-adoptions-api-1.0.0",
"title": "Pets and Adoptions API",
"order": 3,
"content": {
"type": "apiUrl",
"url": "https://api.swaggerhub.com/apis/portal/Pets-and-Adoptions-API/1.0.0/swagger.json"
}
}'📌 You can have multiple API references and documents in one product. To learn more, see Add APIs to Product and Add Docs to Product.
Edit Document Content
To update the contents of a Markdown document, use the PATCH Document endpoint.
curl --location --request PATCH 'https://api.portal.swaggerhub.com/v1/documents/<DOCUMENT-ID>' \
--header 'Authorization: Bearer <YOUR-SWAGGER-APIKEY>' \
--header 'Content-Type: application/json' \
--data '{
"content": "# Updated Document Title\nThis is the updated content of the document."
}'In this example, replace <DOCUMENT-ID> with the actual document ID you wish to edit, and update the content field with the new content you want to set for the document.
Change Document to external
Use the PATCH Update the contents of a document endpoint to change source property to external. This will disable editing in the Swagger Portal UI. It is possible only in a separate request, no other value can be updated at the same time.
curl --location --request PATCH 'https://api.portal.swaggerhub.com/v1/documents/<DOCUMENT-ID>' \
--header 'Authorization: Bearer <YOUR-SWAGGER-APIKEY>' \
--header 'Content-Type: application/json' \
--data '{
"source": "external"
}'❗ Note: This operation cannot be reverted. Update of document's
sourceproperty to internal is not supported.
Restore Deleted Items
Use the PATCH Patch table of contents endpoint to retrieve deleted ToC entries and set status value to restored.
Sample Request
curl -X PATCH "https://api.portal.swaggerhub.com/v1/table-of-contents/<TOC-ID>" -H "Content-Type: application/json" -H "Authorization: Bearer <YOUR-SWAGGER-APIKEY>" -d '{
"status": "restored"
}'❗ Note: Restoring a table of contents item does not restore its nested child pages.
Revert content to saved state
Use the PATCH Patch table of contents endpoint to revert content to last published state.
Sample Request
curl -X PATCH "https://api.portal.swaggerhub.com/v1/table-of-contents/<TOC-ID>" -H "Content-Type: application/json" -H "Authorization: Bearer <YOUR-SWAGGER-APIKEY>" -d '{
"status": "reverted"
}'❗ Note: No other property can be updated when the
statusfield is set.
Delete an Attachment
Use the DELETE Delete attachment endpoint to remove an attachment (for example, an image embedded in documentation) and its content.
Sample Request
curl --location --request DELETE 'https://api.portal.swaggerhub.com/v1/attachments/<ATTACHMENT-ID>' \
--header 'Authorization: Bearer <YOUR-SWAGGER-APIKEY>'❗ Note: This operation cannot be reverted.