Customize your Run in Postman button for your API consumers

As an API publisher, you can dynamically inject information as environment variables into the embedded Run in Postman button using the Run in Postman API. The Run in Postman API uses the _pm() method to create or update environments in your website's client-side code.

For example, you can use the API to pass sign-in credentials to Postman:

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

Learn how to create, modify, remove, and otherwise manage environments using the Run in Postman API.

Create a new environment

Use the env.create method to create a new environment:

_pm('env.create', 'environment_name', {key: value}, runButtonIndex);

You can't use env.create to create duplicate environments. Calls made with existing environment names will fail.

Create a new environment using API keys entered by your user:

function () {
  var stagingKey = document.getElementById('staging-key-input').value,
    productionKey = document.getElementById('production-key-input').value,
    runButtonIndex = 0,
    envData = {
      stagingKey: stagingKey,
      productionKey: productionKey
    };

  _pm('env.create', 'API Keys', envData, runButtonIndex);
}

The env.create action will return the total number of environments associated with Run in Postman buttons on the page on success and false on failure.

Edit an existing environment

Use the env.assign method to update an environment:

_pm('env.assign', 'environment_name', {key: new_value, new_key: value}, preventOveride, runButtonIndex)

The env.assign method works for environments that you included in the Run in Postman button when you created it, or environments that you added using the env.create method. You can't use env.assign to create new environments. Calls made using env.assign will fail if an environment doesn't already exist.

Update an environment's API keys:

function () {
  var stagingKey = document.getElementById('staging-key-input').value,
    productionKey = document.getElementById('production-key-input').value,
    preventOveride = true;
    runButtonIndex = 0,
    envData = {
      stagingKey: stagingKey,
      productionKey: productionKey
    };

  _pm('env.assign', 'API Keys', envData, preventOveride, runButtonIndex);
}

The env.assign action will return true on success, false on failure.

Replace an existing environment

Use the env.replace method to replace an entire environment:

_pm('env.replace', 'environment_name', {key: value}, runButtonIndex)

You can't use env.replace to replace an environment which doesn't exist.

Replace an environment:

// Existing environment named 'user_data'
{
   auth_token: 'q4yugoiwqu4habddef3897ryq3891s',
   user_id: '823',
   session_data: {}
}

// Replace the 'user_data' environment
_pm('env.replace', 'user_data', {});

The env.replace method will return true on success, and false on failure.

Remove an existing environment

Use the env.remove method to remove an existing environment.

_pm('env.remove', 'environment_name', runButtonIndex)

To remove an environment:

// Existing environment named 'user_data'
{
  auth_token: 'q4yugoiwqu4habddef3897ryq3891s',
  user_id: '823',
  session_data: {}
}

// Remove the 'user_data' environment
_pm('env.remove', 'user_data');

The env.remove method will return true on success or false on failure. The specified environment must exist or env.remove will fail.

Use multiple buttons with separate environments

You can embed multiple buttons on a single page. If you want to include a different environment in each button, enable the segregateEnvironments property.

_pm('_property.set', 'segregateEnvironments', true);

If you enable segregateEnvironments, you will have to use runButtonIndex in all _pm() methods to reference each button according to its position in your page DOM. Because segregateEnvironments is deactivated by default, runButtonIndex is optional by default.

Include the index

If you enable segregateEnvironments, you'll have to use runButtonIndex in all _pm() methods to reference each button according to its position in your page DOM. The runButtonIndex is an integer.

var runButtons = Array.prototype.slice.call(document.getElementsByClassName('postman-run-button')),
  runButtonIndex = runButtons.indexOf(elem);

Use the index for jQuery

var runButtonIndex = $('postman-run-button').index(elem);

Get all environments

You can use the get() method to retrieve an array of all the environments.

_pm('_property.get', 'environments')

This will return an array of environments:

[
  {
    "button_index": 0,
    "name": "env1",
    "values": [
      {
        "key": "testKey",
        "value": "testValue",
        "enabled": true
      }
    ]
  }
]

Next steps

After creating a Run in Postman button, you can share your API even more widely by creating documentation in a public workspace.

• To learn how to create API documentation in Postman, visit Document your APIs in Postman.
• To learn how to add your documentation to your public workspaces, visit Publish documentation in Postman.