Creating Run in Postman buttons

One way to share your Postman Collections is to create a stand-alone Run in Postman button. You can embed the button in your website or a README to let developers interact with your API more quickly.

The Run in Postman button also works with API specification formats like OpenAPI and RAML. To create a button for the standard you use, first convert the file to a collection by importing it into Postman or by authoring your specification in Postman to generate a collection.

Contents

Creating a Run in Postman button

Make sure you're signed in to your Postman account, and that you have a collection to share.

  1. In the Postman app, open the collection you want to share.
  2. Next to the collection name, expand the collection details and click the Share button to open a modal.
  3. Tab over to Embed.
  4. Click Generate code.
  5. Choose a dynamic or static button:

    • Dynamic button: This button uses JavaScript, HTML and CSS, so you can customize the button for a website. You can also access the Run in Postman API to dynamically create and update environments.
    • Static button: This button uses Markdown, so you can display it in a README, blog, or other Markdown document.
  6. You can optionally include an environment to embed with your collection. On the right, click the Environment drop-down and choose the environment.
  7. Click Copy to clipboard.
  8. Embed the code where you would like the button to be displayed.

Create a button

Your embed code will include your collection's ID. In the examples below, :collection_id is a placeholder for that ID. If you choose to include an environment in your button, the code will also have the environment parameter.

Sample markdown snippet:

[![Run in Postman](https://run.pstmn.io/button.svg)](https://www.postman.com/run-collection/:collection_id)

Sample HTML snippet:

<div class="postman-run-button"
data-postman-action="collection/import"
data-postman-var-1=":collection_id"></div>
<script type="text/javascript">
  (function (p,o,s,t,m,a,n) {
    !p[s] && (p[s] = function () { (p[t] || (p[t] = [])).push(arguments); });
    !o.getElementById(s+t) && o.getElementsByTagName("head")[0].appendChild((
      (n = o.createElement("script")),
      (n.id = s+t), (n.async = 1), (n.src = m), n
    ));
  }(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
</script>

You can include an environment along with a collection in your Run in Postman button. The dynamic button gives you access to the Run in Postman API to create and modify environments.

Keeping your collections up to date

When you make changes to a collection that's shared with a Run in Postman button, you'll need to manually update the button's collection link so that your users import the most recent version of your collection.

  1. In the Postman app, open the original collection.
  2. Next to the collection name, expand the collection details and click the Share button to open a modal.
  3. Tab over to Embed > Update link.

Embed button

The collection imported by users is a copy of the original, so updates made to the original are not updated in these copies. Users must import the latest collection to see updates made to the original collection.

Next steps

Read more about the Run in Postman API and learn how to add and update environments with your button.