<commit_before>---
title: "Run in Postman button API"
order: 335
page_id: "run_button_API"
warning: false
contextual_links:
  - type: section
    name: "Prerequisites"
  - type: link
    name: "Intro to Postman API"
    url: "https://learning.postman.com/docs/postman/postman-api/intro-api"
  - type: section
    name: "Next Steps"
  - type: link
    name: "Intro to scripts"
    url: "https://learning.postman.com/docs/postman/scripts/intro_to_scripts"
---


The JavaScript Run in Postman API is accessible through the dynamic Run in Postman button. The API is a collection of JavaScript methods that you can leverage to alter your button's behavior and affect environments included in your button. Write your functions in the button's script in your website's source code to do any of the following:

* Create a new environment
* Modify an existing environment
* Replace an environment
* Use several buttons on a single page with segregated environments, each button with its own environment

> Learn more about more about [environments and variables](/docs/postman/collection-runs/using-environments-in-collection-runs/) in Postman.

## Creating a new environment

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

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

> `env.create` cannot be used to create duplicate environments. Calls made with existing environment names will fail.  

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

```javascript
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 the `env.create` action will return truth on success, false on failure.

## Editing an existing environment

Use the `env.assign` method to modify an environment:

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

> The `env.assign` method works for environments that were included in the Run in Postman button when it was created, or environments that were added via the `env.create` method.
> `env.assign` cannot be used to create new environments. Calls made using `env.assign` will fail if the environment does not already exist.

Update an environment's API keys:

```javascript
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 truth on success, false on failure.

## Replacing an existing environment

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

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

> `env.replace` cannot be used to replace an environment which does not exist.

Replace an environment:

```javascript
// Existing environment named 'user_data'
{
   auth_token: '<PASSWORD>',
   user_id: '823',
   session_data: {}
}

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

The `env.replace` method will return truth on success, false on failure.

## Using multiple buttons

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

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

### Include the index

If `segregateEnvironments` is enabled, you'll have to use `runButtonIndex` in all pm() methods to reference each button according to its position in your page [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model). The `runButtonIndex` is represented by an integer.

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

### Using the index for jQuery

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

## Next steps

Learn how to [create API documentation](/docs/postman/api-documentation/documenting-your-api/) from Postman, and then add your documentation to Postman's [API Network](/docs/postman-for-publishers/api-network/add-api-network/).<commit_msg>Changed verb from command to -ing<commit_after>---
title: "Run in Postman button API"
order: 335
page_id: "run_button_API"
warning: false
contextual_links:
  - type: section
    name: "Prerequisites"
  - type: link
    name: "Intro to Postman API"
    url: "https://learning.postman.com/docs/postman/postman-api/intro-api"
  - type: section
    name: "Next Steps"
  - type: link
    name: "Intro to scripts"
    url: "https://learning.postman.com/docs/postman/scripts/intro_to_scripts"
---


The JavaScript Run in Postman API is accessible through the dynamic Run in Postman button. The API is a collection of JavaScript methods that you can leverage to alter your button's behavior and affect environments included in your button. Write your functions in the button's script in your website's source code to do any of the following:

* Create a new environment
* Modify an existing environment
* Replace an environment
* Use several buttons on a single page with segregated environments, each button with its own environment

> Learn more about more about [environments and variables](/docs/postman/collection-runs/using-environments-in-collection-runs/) in Postman.

## Creating a new environment

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

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

> `env.create` cannot be used to create duplicate environments. Calls made with existing environment names will fail.  

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

```javascript
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 the `env.create` action will return truth on success, false on failure.

## Editing an existing environment

Use the `env.assign` method to modify an environment:

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

> The `env.assign` method works for environments that were included in the Run in Postman button when it was created, or environments that were added via the `env.create` method.
> `env.assign` cannot be used to create new environments. Calls made using `env.assign` will fail if the environment does not already exist.

Update an environment's API keys:

```javascript
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 truth on success, false on failure.

## Replacing an existing environment

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

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

> `env.replace` cannot be used to replace an environment which does not exist.

Replace an environment:

```javascript
// Existing environment named 'user_data'
{
   auth_token: '<PASSWORD>',
   user_id: '823',
   session_data: {}
}

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

The `env.replace` method will return truth on success, false on failure.

## Using multiple buttons

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

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

### Including the index

If `segregateEnvironments` is enabled, you'll have to use `runButtonIndex` in all pm() methods to reference each button according to its position in your page [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model). The `runButtonIndex` is represented by an integer.

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

### Using the index for jQuery

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

## Next steps

Learn how to [create API documentation](/docs/postman/api-documentation/documenting-your-api/) from Postman, and then add your documentation to Postman's [API Network](/docs/postman-for-publishers/api-network/add-api-network/).
{'fraction_non_alphanumeric': 0.10586844368013758, 'fraction_numerical': 0.0017196904557179708, 'mean_word_length': 4.649666059502125, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 15, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1374405', 'n_tokens_mistral': 2705, 'n_tokens_neox': 2587, 'n_words': 970}