Share and collaborate on APIs in Postman

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 APIs with collaborators by going to the API you want to share in the sidebar. Select the more actions icon next to the API you want to share, then select Share.

For more details about sharing APIs, see Share your work in Postman.

Collaborating on APIs

You can move APIs to shared private, team, or public workspaces to collaborate with your team on API development.

You must be an Admin on an API or the Workspace Admin to move the API to another workspace. Learn more about roles and permissions.

To move an API to a shared workspace, do the following:

1. Select APIs in the sidebar.

2. Select the more actions icon next to an API and select Move.

3. Use the search box to find the workspace you want to move the API to, or select the filter icon to filter workspaces by visibility.

   You can move APIs to personal, private, team, and public workspaces that you have access to. You can't move APIs from team, private, or public workspaces to a personal workspace.

4. Select the workspace, then select Move API. Any collections in the API will move with the API to the new workspace.

Tagging APIs

Tagging APIs is available on Postman Enterprise plans. You can apply shared tags to workspaces, collections, and APIs. Tags can be 2 to 64 alphanumeric characters in length and must start with an alphabetical character. Tags can contain dashes but no other special characters or spaces. You can add up to five tags.

You can use shared tags to organize and search for APIs. Once you add tags to an API, you can select a tag to search for APIs and other elements with the same tag.

To learn more about searching using tag names in Postman, see Search Postman. You can use tags when searching elements in your Private API Network. You can also use tags to search for elements to add and elements to request to add to your Private API Network.

To add tags to an API, do the following:

1. Select APIs in the sidebar.

2. Select an API.

3. Select the Tags section to edit it.

   

4. Select an existing tag or enter a new tag. If you're adding a new tag, enter the new tag name and then select Create "tag-name".

   

5. Select the area outside of the Tags section to save your changes.

To remove tags from an API, do the following:

1. Select APIs in the sidebar.
2. Select an API.
3. Select the Tags section to edit it.
4. Select the close icon next to a tag.
5. Select the area outside of the Tags section to save your changes.

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, you'll receive a notification when a team member updates the API's definition, adds an element to the API, or adds a comment to the API.

Select Watch to start watching the API.

For more information about the changes to the API, select the notifications icon in the Postman header.

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

You won't receive notifications for changes that you made.

Commenting on APIs

You can add one or more comments to an API. Use comments to discuss your APIs with collaborators in Postman, keeping the conversation in context and available to other stakeholders.

API producers (Admin role or Editor role) can add comments to an API. API consumers (Viewer role) can't add comments to an API and won't see comments made by API producers. However, API consumers can comment on published versions of an API.

To add a new comment to an API, do the following:

1. Select APIs in the sidebar and select the API you want to comment on.
2. Select the comments icon in the right sidebar.
3. Enter your comment and select Comment.

You can also add comments to collections you've added to your API and to requests and folders in that collection. Learn more about commenting on a collection.

To leave an inline comment on an API definition, do the following:

1. Select an API in the sidebar to expand it.
2. Select Definition under the API, then select the definition file you want to comment on.
3. Switch to comment mode by selecting the comments icon in the editor pane.
4. Highlight part of the definition, enter your comment, and select Comment.

Formatting API comments

Comments (including inline comments) support the same formatting features as the Postman editor. Use common keyboard shortcuts to format text, like ⌘+B or Ctrl+B to make text bold, or paste formatted text and tables from a word processor or other source. You can also drag or paste an image into your comment, or add and edit links.

Postman supports Markdown in comments. For example, enter # followed by a space to start a new heading, or enter --- to add a horizontal line. You can also copy existing Markdown code, including lists and tables, and paste it into the editor to instantly format it.

To mention a collaborator in a comment, type @ followed by their name, then choose the person from the auto-suggested list. When you mention a teammate in a comment, Postman sends them a notification.

To learn more about formatting content, go to Writing descriptions in the Postman editor.

Editing, deleting, or linking to an API comment

To manage API comments, select an API or a definition file in the sidebar, then select the comments icon in the right sidebar.

Select the more actions icon next to a comment and do one of the following:

• Select Copy link to copy a direct link to the comment to your clipboard. Share the link with your teammates so they can view or reply to the comment.
• Select Edit to make changes to the comment.
• Select Delete to delete the comment.

If you have the Admin role for the workspace, you can delete comments made by any contributor, but you can't edit comments made by others.

Replying to an API comment

To reply to an API comment, select an API or a definition file in the sidebar, then select the comments icon in the right sidebar. Select Reply on the comment you want to reply to. Enter your reply and select Reply.

Resolving API comments

You can resolve a comment after it's been addressed. Select an API or a definition file in the sidebar, then select the comments icon in the right sidebar. Select the resolve icon to resolve a comment and any associated replies.

You can't undo resolving a comment, but you can view resolved comments by selecting the filter icon in the comments pane.

Commenting on published APIs

You can publish your API to share the current state of your API with consumers. Keep in mind the following when publishing an API:

• When you publish an API version, comments made by API producers aren't published with the API.
• API consumers can't add comments to an API, but they can add comments to a published API version.

Commenting on Git-linked APIs

You can connect a Git repository to your API to sync your API between Postman and the repository. Keep in mind the following differences when commenting on Git-linked APIs:

• Comments are associated with a branch. If you add a comment while working on one branch, those comments won't be visible when you switch to another branch.
• You must commit and push changes on a branch before you can add a new comment on that branch. (You can reply to an existing comment without committing and pushing changes.)
• When you merge a branch, comments remain on the branch being merged and aren't merged to the target branch.

Using the changelog

You can view a history of changes to your API definitions and all linked collections. To access the changelog, open an API, then select the changelog icon in the right sidebar.

If you connect your API to a Git repository, the changelog is replaced by the Source Control pane. Learn more about API version control.

The changelog shows a list of changes made to the definition and associated elements. Select each entry for more details.