Submission guidelines

Adding your team profile and collection docs to the API Network or templates can expose your services to more potential users within the Postman community and provide them with the tools to onboard and adopt your API. To get the best out of your listing, follow a few tips that will aid discovery of your documentation, making it and your collection templates as usable as possible.

API Network Homepage

Check your collection in the app

Your documentation represents a Postman collection, with both the textual information content—and the executable requests bundled via the Run in Postman button—pulled from your collection setup in Postman. For this reason, it's worth walking through the process of importing the collection yourself, checking the information that appears inside the Postman app as well as in the docs (for example descriptions on the collection, requests, and parameters).

If your collection contains lots of requests, consider grouping them into folders to make the documentation and imported templates easier to navigate.

Check your docs on the web

When you publish documentation for a Postman collection, you will author the content inside the Postman app in Markdown, but consumers will view it in the web browser as HTML. For this reason, it's essential to read through your docs in the browser to get a feel for how they will walk developers through the process of using your API, and to ensure your collection information is rendering as expected (this is particularly important if you're using variables to populate some of the content).

Tailor your examples

The sample code section in your docs will play a significant role in how effectively developers are able to onboard with your API or use your template requests. Your collection examples will automatically populate in the docs code, so it's worth taking the time to ensure that the examples contain readable, prototypical usage of your API endpoints.

Add contextual material

When developers attempt to learn how to integrate with an API, they need to understand more than just what each endpoint receives and returns. By introducing your API with contextual material explaining its purpose at a high level, for example outlining how the different requests fit together to build client applications, you will help new users get off to a more effective start. Ideally include quickstart information that lets developers make a request to your API as soon as possible.

If your API or template requires authentication, make sure you include instructions explaining what developers need to do to acquire and use credentials. Other top level info such as rate limits, content types, or settings that apply across endpoints can appear in your collection description so that they render at the top of your documentation page.

Complete your profile

When you publish to the API Network, potential users will initially see your team profile, with APIs listed under it. Taking the time to fill out your team profile gives consumers a clear sense of who a collection is published by—helping them to decide whether to try it out or not. You can include a team name, description, logo, and custom URL.

When you publish to the Postman templates, potential users can see your profile if they search via the web. Taking the time to fill out your profile gives you a chance to introduce yourself to the people considering using your templates. You can include your name, description, a photo, and customize your URL.

Complete your API listing

Your listing should provide the information developers need to know in order to decide whether they want to try the API or collection out. Try to choose a descriptive name that conveys the purpose of your API without users having to click it to find out more detail. In your description, try to include an overview of what the API / collection does, with enough detail for consumers to figure out whether it's likely to fit their use case. You can include a name, summary, description, and categories that will determine how your API or collection is listed when users browse the network / templates.

Sample listings

The API Network includes lots of effective listings you can use for inspiration when building your own:

There are also lots of inspiring templates already published that you can learn from: