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 in Postman. 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, and 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.

  1. In Postman, select an API in the sidebar and click (Three dots icon) to open the menu, then choose Share API.

    Edit API
  2. Select a workspace, choose if you want to remove the API from the current workspace after sharing, then click Share and Continue.

    Share API to Workspace

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

    API Workspace Roles

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.

Watching APIs

The watch option enables you to receive an email or in-app notification when a team member belonging to the same workspace modifies the API, for example updating the schema, attaching an element to the API, adding a comment to the API and so on.

Select Watch to start watching the API.

Watch Option

Click the bell icon on the top right corner to view the notification. The popup will indicate further information about the change that was made to the API.

Notification Watch API

You will also receive an email with the information regarding who has made the change, what the change was, and when it was made.

You will not receive notifications for changes made by yourself.

Commenting on APIs

You can discuss your APIs with collaborators in Postman, keeping the conversation in context and available to other stakeholders. Anyone with access to the API can comment.

To leave a comment on an API, open APIs in the left sidebar and select the API version you want to comment on. Switch to comment mode, enter your comment, and Add comment to publish it.

api comment app

You can leave inline comments on the API schema by highlighting what you want to comment on.

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, deleting, or linking to a comment

To edit, delete, or link to 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, the bin icon to delete, or the anchor icon to get a direct link to the comment.

api comment manage

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

Using the Changelog

You can view a changelog of your API schemas and all linked collections in the context bar. You can also create releases of an API from the changelog.

To see the changelog, open an API version, then click the changelog icon. (Changelog icon)

You will see a list of changes made to the schema and associated elements. Each release is shown, and the top of the list will show any unreleased changes. Click to expand each entry for more details.

Select + Release changes at the top of the list to create a release from unreleased changes. For more information, see Working with API releases.


Next steps

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