Collaborate in Postman using comments

Commenting is one of Postman's most practical collaborative tools that can be used on both the publisher and consumer sides of APIs. Through interactive communication, commenting removes ambiguity, improves user experience, and helps to increase the adoption of API-driven services.

API publishers can use commenting throughout the API lifecycle to improve the API design and resolve API consumers' issues. API consumers can use commenting to ask API publishers questions and receive support about the APIs they use.

Comments aggregate at the collection level so that you can check all communication about various elements of the collection in one place. Select the comment header to jump to the commented element.

Use comments in Postman

Postman provides two types of commenting: global and inline. When you add a comment, Postman notifies other collection contributors about your comment. To specify a teammate, use @, then select the person from the list. They'll receive an email and an in-app notification. Select the notifications icon in the Postman header to view in-app notifications. You can also copy a link to the comment and paste it in your team channels.

If your teammate doesn't have access to the collection they've been mentioned in, they'll need to request access before they can read the comment.

For general questions about a collection and its elements, you can use global comments in the right sidebar.

You can add inline comments on the following items:

Parameters, the request body, and scripts that are part of a request or example response
Pull requests in forked collections

The following example shows an inline comment on an example response.

You can also add comments to APIs and API definitions in the Postman API Builder. Learn more about commenting on APIs.

Commenting best practices

Use comments to discuss your work with your teammates in Postman. Reply to a comment to keep the discussion going, or resolve a comment if it's been addressed. If you have questions or feedback, you can let your teammates know by mentioning them in your comments.

Encourage users in your public workspace or Partner Workspace to use comments if they get errors or have any questions. Doing so will help establish a rapport with your users and help to resolve their errors faster. For example, your users might get a 400 response and wonder why or have questions about how to enter an API key.

Avoid using comments to document your APIs. Postman automatically generates documentation for your collection. To access it, select your collection in the sidebar, then select View complete documentation in the workbench. You can edit and build upon your documentation to make it better for your users.

Global comments

You can add global comments to a collection, folder, request, example, or pull request in Postman.

You must have access to a collection to add comments to it.

To add a comment to a collection, do the following:

Select Collections in the sidebar and select the collection, folder, request, example, or pull request you want to comment on.
Select Comments in the right sidebar and enter your comment.

Postman supports Markdown in comments. See the Markdown Cheatsheet on GitHub for tips on formatting.
Select Comment to add your comment.

Format 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 learn more about formatting content, go to Writing descriptions in the Postman editor.

Inline comments

Use inline comments to comment on a specific part of a request, example, or script. You can add comments to parameters, headers, request bodies, and lines of code in scripts.

Comment on part of a request or example

To add an inline comment to a request or example, do the following:

Open the request or example.
Select the part of the request or example you want to comment on. You can select text within a query parameter, path parameter, header, and request body (form-data, x-www-form-urlencoded, and raw).
Right-click the selection, then select Comment.
Enter your comment.
Select Comment to add your comment.

Comment on a script

To add an inline comment to a script, do the following:

Open a pre-request or post-response script.
Select a line of code in the script. A comments icon appears next to the line of code.
Select the comments icon .
Enter your comment and select Comment. A comments icon remains next to each line that has a comment.

Comment on a pull request

To add an inline comment to a pull request, do the following:

Open the pull request.
Select the comments icon next to a change and enter your comment.
Select Comment to add your comment.

To learn more about forking collections and using version control in Postman, go to Version control for Postman collections and environments.

You can get a link to a comment you can share with others. You can also edit or delete a comment.

Select a collection, folder, request, example, or pull request, then select Comments in the right sidebar. Or select an inline comment.
Select View actions inside the comment, then select Copy link to copy a direct link to the comment to your clipboard.

If you're a Workspace Admin, you can delete contributor comments, but you can't edit contributor comments.

Respond to comments

You can reply to a comment to keep the conversation going. Replies are grouped with the original comment, so you can have more than one comment thread on a collection, folder, request, example, or pull request. When you reply to a comment, the user who added the comment will receive a notification about your reply. You can resolve a comment after it's been addressed.

On a comment, select Reply.