How to Add Comments to Collections in Postman

You’re deep in a Postman collection someone else built. No documentation. No context. Just a folder full of requests with cryptic names like test_v2_final_REAL.

Sound familiar?

That’s exactly the problem comments in Postman solve. They let your team leave context, flag issues, and communicate directly inside the tool where the work happens — no more jumping between Slack, Notion, and your API workspace trying to piece together what a request actually does.

This guide walks you through exactly how to add comments to collections in Postman, why it matters more than most people think, and how to use them to keep your team aligned without the chaos.

What Are Comments in Postman?

Comments in Postman are inline notes you can attach directly to collections, folders, and requests inside your workspace. They function like annotations — letting you explain logic, flag bugs, ask questions, or leave instructions for anyone who opens the collection later.

Think of it as Google Docs-style collaboration, but built into your API environment.

Since Postman introduced collaborative workspaces, comments have become one of the most underused but highest-leverage features available. According to Postman’s 2023 State of the API Report, over 83% of teams using APIs say collaboration is their biggest challenge — and yet most teams still communicate about APIs outside the tool itself.

Comments fix that gap.

Why Adding Comments to Postman Collections Matters

Before diving into the how, it’s worth understanding the why — because most people skip comments until they’re burned by the absence of them.

Teams work across time zones. When someone in Singapore builds a collection and someone in Toronto inherits it, there’s no live handoff. Comments become the asynchronous bridge.

APIs break. When something fails, comments that say “this endpoint returns a 401 if the token is expired — refresh using /auth/refresh” save everyone a 45-minute debugging spiral.

Context gets lost fast. According to a McKinsey study, knowledge workers spend 19% of their time searching for information that already exists somewhere. Comments inside Postman keep that context exactly where you need it.

Reviews happen inside Postman. For teams doing API design reviews, comments let reviewers annotate specific requests without needing a separate code review tool.

The bottom line: commenting isn’t documentation overhead. It’s how you stop your team from wasting time on problems that have already been solved.

How to Add Comments to a Collection in Postman

Here’s the exact process, step by step.

Open Your Postman Workspace

Start by launching Postman and navigating to the workspace that contains the collection you want to comment on. Make sure you’re logged into your Postman account — comments are a cloud feature and require you to be signed in.

If you’re working in a local (offline) workspace, comments won’t be available. You need to be in a Team, Personal cloud, or Public workspace.

Locate the Collection in the Sidebar

In the left sidebar, find the collection you want to annotate. You’ll see all your collections listed under the Collections tab.

Hover over the collection name and you’ll see a set of action icons appear on the right side of the row.

Click the Comment Icon

Look for the speech bubble icon (💬) that appears when you hover over the collection. Click it.

This opens a comment panel on the right side of the screen. This is where all comments for that collection live — both yours and your teammates’.

Write Your Comment

In the comment input box at the bottom of the panel, type your comment. Postman supports:

• Plain text notes
• @mentions to tag specific teammates
• Markdown formatting (bold, code snippets, links)

Keep comments specific and actionable. Instead of writing “needs fixing,” write “this request fails when the user_id param is empty — add a pre-request script to validate it before sending.”

Post the Comment

Click the Post button or press Cmd + Enter (Mac) / Ctrl + Enter (Windows).

Your comment is now live and visible to everyone with access to that workspace. Teammates with notifications enabled will receive an alert.

How to Add Comments to Requests and Folders Inside a Collection

You’re not limited to top-level collection comments. You can annotate individual folders and requests too — which is often where the most useful context lives.

Adding a Comment to a Specific Request

Open the collection and click on the individual request you want to comment on. Once the request is open in the main panel, look for the Comments tab at the top of the right panel area — it sits alongside the Documentation tab.

Click it, and you’ll see the same comment interface. Write your note and post.

This is especially useful for flagging things like:

• Auth requirements specific to that endpoint
• Known rate limits
• Expected response structures
• Error codes and what they mean

Adding a Comment to a Folder

Right-click on any folder inside a collection. A context menu will appear with a Comment option. Click it to open the comment panel for that specific folder.

Use folder-level comments for broader context — like explaining the purpose of a folder group (“these are all sandbox environment requests — don’t use in production”) or flagging a dependency between folders.

How to Resolve and Manage Comments

Comments left unmanaged create noise. Postman gives you tools to keep things clean.

Resolving a Comment

Once a comment has been addressed — a bug is fixed, a question is answered, a note is no longer relevant — you can resolve it. Hover over the comment and click the checkmark icon that appears. Resolved comments are hidden from the main view but remain accessible if you want to review them later.

Pro tip: Make it a team habit to resolve comments as part of your PR or sprint closure process. Stale comments are almost as confusing as no comments at all.

Replying to Comments

Click the Reply option under any comment to start a thread. This is useful for back-and-forth discussion about a specific issue — keeping it attached to the relevant request rather than buried in a separate Slack thread.

According to Postman data, teams that use Postman’s collaborative features (including comments) resolve API issues 35% faster than those relying solely on external communication tools.

Deleting a Comment

If you need to remove a comment entirely, hover over it and select the delete option. Note that you can only delete comments you’ve authored — you can’t remove a teammate’s comment.

Best Practices for Using Comments Effectively

Using comments well is a skill. Here’s what separates good documentation from comment clutter:

Be specific, not vague. A comment that says “see documentation” helps nobody. One that says “this relies on the auth token from the /login call — run that first” is immediately useful.

Use @mentions to create accountability. If a comment requires action, tag the person responsible. @sarah can you confirm the expected response schema here? is a task. “Needs review” is not.

Keep comments close to what they describe. Collection-level comments for overall context. Request-level comments for endpoint-specific details. Don’t write a paragraph on the collection when it belongs on a specific request.

Date-sensitive comments deserve an expiry note. If you’re writing a comment like “this token works until Q2,” add a note to remove or update it. Comments that age badly are worse than no comments.

Standardize comment formats across your team. Consider a lightweight convention — like [BUG], [NOTE], [TODO] prefixes — so anyone scanning comments knows immediately what action is needed.

Common Issues When Adding Comments in Postman

Can’t see the comment icon? You’re likely in a local workspace or offline mode. Switch to a cloud workspace to access comments.

Comments not notifying teammates? Check workspace notification settings. Each member needs to enable email or in-app notifications under their Postman account settings.

Comment panel not appearing? Try refreshing the workspace or clearing your cache. If the issue persists, check if your Postman version is up to date — older versions may not fully support the comment panel UI.

Can guests or viewers leave comments? It depends on workspace permissions. Guests with Viewer access can read comments but typically cannot post them. You may need to update their role to Commenter or Editor.

How Comments Fit Into Your Broader API Collaboration Workflow

Comments are one layer of a larger collaboration system. Here’s how they stack with other Postman features:

Documentation explains what an API does for external consumers. Comments are internal — they explain why decisions were made, flag issues, and capture evolving context during development.

Version control tracks what changed. Comments explain why something changed or what to watch out for with a specific version.

Test scripts enforce behavior. Comments on test scripts explain the logic behind assertions that aren’t immediately obvious.

According to Postman’s API Economy research, organizations with high API maturity are 3x more likely to have formal internal documentation and collaboration processes in place. Comments are a core part of that process — not an optional nice-to-have.

Teams shipping multiple API products simultaneously report that structured commenting reduces onboarding time for new team members by an estimated 30-40%, simply by making institutional knowledge discoverable inside the tool.

Conclusion

Adding comments to collections in Postman is one of those small habits that compounds fast. The first comment you leave saves you five minutes. The tenth saves your team an afternoon. The hundredth becomes the difference between an API workspace that’s a collaborative asset and one that’s a black box nobody wants to touch.

The process itself is simple — open the collection, click the comment icon, write something useful, post it. But the discipline of making it a team standard? That’s where the real return comes from.

Start with your messiest collection. Leave three comments today. See how your team responds.

If you want to bring that same discipline to your outbound pipeline — where most teams are working from half-documented targeting lists and campaigns that never get iterated on — that’s exactly what we build at Salesso. Book a strategy meeting and we’ll walk you through how we approach it.