Code with Run in Postman buttons

Some API publishers use Run in Postman buttons alongside their own API documentation. If users input data in a developer portal, for example, the Run in Postman API can dynamically inject this provided information as environment variable values into the embedded Run in Postman button.

The Run in Postman API uses the _pm() method to create or update environments in your website's client-side code through existing dynamic Run in Postman buttons.

As another example, you can use the API to pass sign in credentials to Postman:

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

Creating 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.

Editing 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.

Replacing 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, false on failure.

Removing 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.

Using 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.

Including 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);

Using the index for jQuery

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

Getting 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 API documentation overview.
• To learn how to add your documentation to your public workspaces, visit Publish your docs.