Managing and sharing APIs

When you define your APIs in Postman using the API Builder, each API is associated with a workspace. You can share access to your APIs, discuss them in comments, and view schema activity.

Sharing APIs

You can share an API via its workspace either in the Postman app or the web dashboard. By sharing your workspace with collaborators, you can provide access to the API via designated roles with specific permissions, including Viewer and Editor.

The Viewer role is only available on certain Postman plans.

If you share an API to a workspace, members of the workspace will have access to any shared elements linked to the API (for example documentation, test suites, monitors). Workspace members can view elements linked to an API but can only edit if an element is also shared within the workspace. If you delete the API or remove it from the workspace, members will still have access to those shared elements unless you remove them also.

In the Postman app, select an API in the sidebar and click (...) to open the menu, choosing Share API.

Edit API

Select a workspace and click Share and Continue.

Share API to Workspace

Configure access levels for collaborators in your workspace and click Save Roles.

API Workspace Roles

You can also share APIs in the web dashboard by navigating to APIs and clicking Share next to the API.

Share API in Dashboard

In addition to sharing an API via its workspace, you can also share it to the private API network. Doing this allows your team to learn about and access these APIs and start using them right away. Learn more about adding your API to the private network.

API list

Commenting on APIs

You can discuss your APIs with collaborators in the Postman app or web dashboard, keeping the conversation in context and available to other stakeholders. Anyone with access can comment, and comments will be visible in both the app and the dashboard.

To leave a comment on an API using the Postman app, open APIs in the left sidebar and select the API you want to comment on. Click Comments at the top-right, enter your comment, and Add comment to publish it.

api comment app

To comment on an API in the web dashboard, navigate to APIs, select the API you want to comment on, and click Comments at the top-right of the page. Enter your comment, and Add comment to publish it.

api comment dashboard

Formatting comments

You can use Markdown in your comments—check out the Markdown Cheatsheet on Github for tips on formatting.

If you want to call the attention of a collaborator in comment, you can tag them by typing @ followed by their name—choose the person from the auto-suggested list. When you tag a member in your comment, Postman will send them a notification.

Editing and deleting comments

To edit or delete one of your comments, navigate to the comment section and hover over the comment you wish to manage. Click the pen icon to edit the comment, or the bin icon to delete.

api comment manage

With Admin permissions you can delete comments made by any contributor, but you cannot update or modify comments.

Viewing API events

You can view a changelog of your API schemas in APIs > Design. Click View changelog.

Schema Changelog Button

Schema Changelog

You will see a list of events on the schema and can click to expand each entry for more detail.

You can use the Restore link to revert the schema to a previous state.

Schema Restored

Next steps

For more info on working with the API Builder in Postman, check out the following resources: