Intro to API documentation

Postman's API Documentation feature lets you view private API documentation or share public API documentation in a beautifully formatted web page.

Postman generates and hosts browser-based API documentation for your collections automatically in real-time. Each collection has a private and public documentation view that Postman generates from synced data in the servers.

Private documentation view

Postman app

To access the private view of your team documentation, go to the sidebar in the Postman app and click the > icon in the collection you want to view. Then click "View in web" to view the documentation for the collection.

view doc sidebar

Postman web

To access the private view of your team documentation, go to your workspaces dashboard.

Click the "View all collections" link.

view all collections

Click a collection name to view the documentation.

click the collection

Public documentation view

After you publish your documentation, you can use the public link to view the documentation.

The public link displays after you publish your documentation. A link to this published documentation is also accessible in the "Published" dropdown from the private documentation view.

Creating documentation

You can create documentation in a few different ways:

What gets automatically generated?

Documentation for your API includes:

  • Sample requests, headers, and other metadata
  • Descriptions associated with requests, folders, and collections
  • Generated code snippets in some of the most popular programming languages
  • Run in Postman button

Postman uses ordered requests and folders to organize documentation in sections to reflect the structure of your collection.

You can customize descriptions using Markdown styling with embedded graphics to complement your documentation.

Postman supports GitHub-flavored Markdown so you can include tables. When including block elements, make sure you leave an empty line before and after to avoid any rendering issues.

example of published documentation

To include helpful cross-references for your readers, you can hyperlink to these parts within the generated documentation:

  • Introduction headers
  • Requests
  • Folders
  • Responses

The links are generated using IDs for the requests, folders and responses. If you click on any of these, the URL in your browser should update to a link which points to this specific part of the documentation. You can hyperlink to these parts using this link.

anchor tag id

Note: You cannot link to arbitrary parts of the documentation by manually creating an ID.

Commenting on Private Documentation

You can post comments on your API documentation to share information with your colleagues. You can save interactions with your teammates, add information that does not fit anywhere else, and can have discussions and more.

You can post comments on your documentation by navigating to the documentation section from the Postman App. To learn more about accessing the documentation section, see viewing documentation.

Once you access the documentation section, the comments section appears, as shown below:

Comments New

Click Comments to bring up the 'Add comment' dialog, as illustrated above. Write your comment and click 'Add comment'. Your comment is now posted.

Note: You can post comments only on Private Documentation.

Free documentation views with your Postman account

Public and private documentation each receive 1000 free views per month. You can check your usage limits through the Postman API or the account usage page.