Creating Run in Postman buttons

You can use The Run in Postman button to share your Postman Collections. You can embed the button in your website to give developers immediate access to your API endpoints.

The Run in Postman button also works with API description formats like Swagger and RAML. To create a button for the framework you use, convert your file to a collection by importing it into Postman.

Contents

• Creating a Run in Postman button
• Keeping your collections up to date
• Next steps

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 create a button for.
2. Next to the collection name, click the ellipsis (...) > Share.
3. At the top of the modal that appears, click Embed.
4. Click Generate code.

5. Choose a static or dynamic button:

   • Dynamic button: This button uses HTML and CSS, and gives you access to the Run in Postman API.
   • Static button: This button uses Markdown.
6. You can include an environment that will import along with your collection. On the right, click the Environment drop-down and choose the environment. Learn more about including environments in your button.
7. Click Copy to clipboard.
8. Embed the code where you would like the button to be displayed.

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:

<a href="https://www.postman.com/run-collection/:collection_id" target="_blank">
  <img src="https://run.pstmn.io/button.svg" alt="Run in Postman">
</a>

Keeping your collections up to date

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

1. In the Postman app, open the collection with the button you need to update.
2. Next to the collection name, click the ellipsis (...) > Share.
3. At the top of the dialog, click Embed > Update link.

Using environments with your button

You can include environments in your Run in Postman button. When developers click the button from your API documentation or website, the environment will be imported along with the collection into their Postman app, and the user can enter their own variable values. Learn more about environments and variables.

If you're using the dynamic (HTML) button, you can use the Run in Postman API to alter your button's behavior. Use the button to create and modify environments, or have multiple buttons on a single page, each with its own environment.

Include an environment in your button

You can add environments to both static and dynamic Run in Postman buttons.

Dynamic buttons: You can include the environment when you generate your button or with the Run in Postman API. If you want to include an environment in a button that already exists, you'll follow the same steps you took to create the button.

Static buttons: With the static (Markdown) button, you can only include the environment when you generate your button. If you want to include an environment in a button that already exists, you'll follow the same steps you took to create the button.

Add environment when you generate a button

You can add an environment to a new button while you're creating it, or to an existing button at any time.

If you add an environment to an existing button, click Update link to save the environment parameter to the embed code. Then, copy the new embed code into your website's code.

1. From the Postman app, go to the collection that you want share with a Run in Postman button.
2. To the right of the collection name, click the ellipses (...) > Share Collection.
3. In the Share dialog, click the Embed tab. If you need to, create your Run in Postman button.
4. On the right, above the code field, click the dropdown to choose an environment. You'll see the code change to include the environment parameter.
5. At the bottom right, click Copy to Clipboard.
6. To embed the button, add the code to your website.

Use the API to include an environment

To use the Run in Postman API, you have to be working with the dynamic (HTML) button.

The JavaScript Run in Postman API uses the _pm() method to create or modify environments in your website's client-side code through existing dynamic Run in Postman buttons. For example, you can use the API to pass login credentials to Postman:

_pm('env.create', 'Spotify', {
  user_id: 'spotifyuser',
  authorization: 'Bearer 1234xyzd'
});

Next steps

Read more about the Run button API and learn how to alter your Run in Postman button's behavior.