> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/postman.md).

# Postman

Manage Postman collections, environments, mock servers, and monitors, and watch a monitor's runs from your AI workflows.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector         | Authentication |
| ----------------- | -------------- |
| Postman (API Key) | API Key        |

#### Postman (API Key)

Connect to Postman with a personal API key to manage collections, environments, mock servers, and monitors.

**Set up in Postman**

1. Prepare the Postman account or service that the workflow will access. Grant access to the required resources and operations.
2. **API Key:** Your Postman personal API key. Generate one in Postman under your avatar > Settings > API keys.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Postman (API Key)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                                     |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes      | Your Postman personal API key. Generate one in Postman under your avatar > Settings > API keys. [Provider instructions](https://learning.postman.com/docs/developer/postman-api/authentication/). |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Postman** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Collection

Create a new Postman collection in a workspace, either empty or from a full collection definition.

**Inputs**

| Field                        | Type            | Required | Description                                                                                                                      |
| ---------------------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Workspace                    | select (string) | Yes      | The workspace the collection is created in. Options load from the selected connection.                                           |
| Collection Name              | string          | Yes      | The name shown for the collection in Postman.                                                                                    |
| Description                  | textarea        | No       | Optional notes about what the collection covers. Markdown is supported.                                                          |
| Collection Definition (JSON) | textarea        | No       | Optional full collection in Postman Collection v2.1 JSON, for example exported from Postman, to import its requests and folders. |

**Outputs**

| Field          | Type   | Description                     |
| -------------- | ------ | ------------------------------- |
| Collection ID  | string | The new collection's ID.        |
| Collection UID | string | The new collection's unique ID. |
| Name           | string | The collection name.            |

#### Update Collection

Rename a collection, change its description, or replace its full contents.

**Inputs**

| Field                          | Type            | Required | Description                                                                                            |
| ------------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| Workspace                      | select (string) | No       | Pick a workspace to narrow the collection list. Options load from the selected connection.             |
| Collection                     | select (string) | Yes      | The collection to update. Options load from the selected connection.                                   |
| New Name                       | string          | No       | A new name for the collection. Leave empty to keep the current name.                                   |
| New Description                | textarea        | No       | A new description. Leave empty to keep the current one.                                                |
| Replace With Definition (JSON) | textarea        | No       | Replaces the entire collection with this Postman Collection v2.1 JSON. Requests not in it are removed. |

**Outputs**

| Field             | Type    | Description                                |
| ----------------- | ------- | ------------------------------------------ |
| Collection ID     | string  | The collection's ID.                       |
| Collection UID    | string  | The collection's unique ID.                |
| Name              | string  | The collection name after the update.      |
| Contents Replaced | boolean | Whether the whole collection was replaced. |

#### Get Collection

Get a collection's details and its full definition.

**Inputs**

| Field      | Type            | Required | Description                                                                                  |
| ---------- | --------------- | -------- | -------------------------------------------------------------------------------------------- |
| Workspace  | select (string) | No       | Pick a workspace to narrow the collection picker. Options load from the selected connection. |
| Collection | select (string) | Yes      | The collection to read. Options load from the selected connection.                           |

**Outputs**

| Field          | Type    | Description                                 |
| -------------- | ------- | ------------------------------------------- |
| Collection UID | string  | The collection's unique ID.                 |
| Name           | string  | The collection name.                        |
| Description    | string  | The collection's description.               |
| Request count  | integer | The number of requests in the collection.   |
| Definition     | object  | The full collection in Postman v2.1 format. |

#### List Collections

List the collections in a workspace, optionally by exact name.

**Inputs**

| Field       | Type            | Required | Description                                                                         |
| ----------- | --------------- | -------- | ----------------------------------------------------------------------------------- |
| Workspace   | select (string) | No       | Only list collections in this workspace. Options load from the selected connection. |
| Exact Name  | string          | No       | Only return collections with exactly this name.                                     |
| Max Results | integer         | No       | The most collections to return. Minimum: 1. Maximum: 500. Default: 50.              |
| Start At    | integer         | No       | Skip this many collections, to continue a previous list. Minimum: 0.                |

**Outputs**

| Field       | Type          | Description                         |
| ----------- | ------------- | ----------------------------------- |
| Collections | object\_array | The collections found.              |
| Next Offset | integer       | Where to continue for more results. |

#### List Workspaces

List the Postman workspaces you can access.

**Inputs**

| Field         | Type            | Required | Description                                                                                    |
| ------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------- |
| Type          | select (string) | No       | Only list workspaces of this type. Available values: Personal, Team, Private, Public, Partner. |
| Max Results   | integer         | No       | The most workspaces to return. Minimum: 1. Maximum: 500. Default: 100.                         |
| Continue From | string          | No       | Continue a previous list.                                                                      |

**Outputs**

| Field       | Type          | Description                         |
| ----------- | ------------- | ----------------------------------- |
| Workspaces  | object\_array | The workspaces found.               |
| Next Cursor | string        | Where to continue for more results. |

#### Create Environment

Create an environment with a set of variables in a workspace.

**Inputs**

| Field            | Type            | Required | Description                                                                                                                                                                                           |
| ---------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace        | select (string) | Yes      | The workspace the environment is created in. Options load from the selected connection.                                                                                                               |
| Environment Name | string          | Yes      | The name shown for the environment in Postman.                                                                                                                                                        |
| Variables        | textarea        | No       | One variable per line, as KEY=value. These values are saved in this workflow's configuration, so fill in sensitive values directly in Postman afterwards, or pass them from an upstream node instead. |
| Secret Variables | string          | No       | Comma-separated keys to mark as secret so Postman masks their values.                                                                                                                                 |

**Outputs**

| Field           | Type    | Description                      |
| --------------- | ------- | -------------------------------- |
| Environment ID  | string  | The new environment's ID.        |
| Environment UID | string  | The new environment's unique ID. |
| Name            | string  | The environment name.            |
| Variable Count  | integer | How many variables were set.     |

#### Create Mock Server

Create a mock server that returns a collection's saved example responses.

**Inputs**

| Field            | Type            | Required | Description                                                                                        |
| ---------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------- |
| Workspace        | select (string) | Yes      | The workspace the mock server is created in. Options load from the selected connection.            |
| Collection       | select (string) | Yes      | The collection whose examples the mock serves. Options load from the selected connection.          |
| Mock Server Name | string          | No       | The name shown for the mock server.                                                                |
| Environment      | select (string) | No       | Optional environment whose variables the mock resolves. Options load from the selected connection. |
| Private          | boolean         | No       | When on, calls to the mock need a Postman API key. Turn off to let anyone call it. Default: true.  |

**Outputs**

| Field    | Type    | Description                      |
| -------- | ------- | -------------------------------- |
| Mock ID  | string  | The mock server's ID.            |
| Mock UID | string  | The mock server's unique ID.     |
| Mock URL | string  | The URL to send requests to.     |
| Private  | boolean | Whether callers need an API key. |

#### List Monitors

List monitors, optionally in one workspace or for one collection.

**Inputs**

| Field         | Type            | Required | Description                                                                             |
| ------------- | --------------- | -------- | --------------------------------------------------------------------------------------- |
| Workspace     | select (string) | No       | Only list monitors in this workspace. Options load from the selected connection.        |
| Collection    | select (string) | No       | Only list monitors that run this collection. Options load from the selected connection. |
| Active Only   | boolean         | No       | Only list monitors that are switched on. Default: false.                                |
| Max Results   | integer         | No       | The most monitors to return. Minimum: 1. Maximum: 250. Default: 50.                     |
| Continue From | string          | No       | Continue a previous list.                                                               |

**Outputs**

| Field       | Type          | Description                         |
| ----------- | ------------- | ----------------------------------- |
| Monitors    | object\_array | The monitors found.                 |
| Next Cursor | string        | Where to continue for more results. |

#### Run Monitor

Run a monitor now and get its test results.

**Inputs**

| Field                      | Type            | Required | Description                                                                                      |
| -------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------ |
| Workspace                  | select (string) | No       | Pick a workspace to narrow the monitor list. Options load from the selected connection.          |
| Monitor                    | select (string) | Yes      | The monitor to run. Options load from the selected connection.                                   |
| Wait For Results (seconds) | integer         | No       | How long to wait for the run to finish before returning. Minimum: 0. Maximum: 280. Default: 120. |

**Outputs**

| Field        | Type    | Description                                |
| ------------ | ------- | ------------------------------------------ |
| Monitor ID   | string  | The monitor that ran.                      |
| Finished     | boolean | Whether the run finished while waiting.    |
| Status       | string  | The run result, such as success or failed. |
| Failed Tests | integer | How many tests failed.                     |

#### Get Monitor

Get a monitor's schedule and the results of its last run.

**Inputs**

| Field     | Type            | Required | Description                                                                               |
| --------- | --------------- | -------- | ----------------------------------------------------------------------------------------- |
| Workspace | select (string) | No       | Pick a workspace to narrow the monitor picker. Options load from the selected connection. |
| Monitor   | select (string) | Yes      | The monitor to read. Options load from the selected connection.                           |

**Outputs**

| Field           | Type    | Description                               |
| --------------- | ------- | ----------------------------------------- |
| Monitor ID      | string  | The monitor's ID.                         |
| Name            | string  | The monitor's name.                       |
| Active          | boolean | Whether the monitor is switched on.       |
| Collection UID  | string  | The collection the monitor runs.          |
| Environment UID | string  | The environment the monitor runs with.    |
| Last Run Status | string  | The result of the last run.               |
| Schedule        | object  | When the monitor runs.                    |
| Last Run        | object  | Details of the monitor's most recent run. |

### Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

#### Monitor Run Completed

Starts the workflow when a Postman monitor finishes a run, by default only when the run fails.

Pick the workspace and monitor to watch. Leave 'Only Failed Runs' on to fire only when a run fails or errors, or turn it off to fire on every completed run. The trigger checks the monitor every 15 minutes, so each active trigger makes about 2,900 Postman API calls a month, which count against your Postman plan's monthly API limit. Postman shows only the latest run, so runs that finish between two checks collapse to the latest one. With 'Only Failed Runs' on, a failed run followed by a passing run before the next check does not fire.

**Configuration**

| Field            | Type            | Required | Description                                                                             |
| ---------------- | --------------- | -------- | --------------------------------------------------------------------------------------- |
| Workspace        | select (string) | No       | Pick a workspace to narrow the monitor list. Options load from the selected connection. |
| Monitor          | select (string) | Yes      | The monitor to watch. Options load from the selected connection.                        |
| Only Failed Runs | boolean         | No       | When on, the workflow starts only for runs that fail or error. Default: true.           |

**Event inputs**

| Field        | Type     | Required | Description                                                |
| ------------ | -------- | -------- | ---------------------------------------------------------- |
| Monitor ID   | string   | Yes      | The monitor that ran. Default: .                           |
| Status       | string   | Yes      | The run result. Default: .                                 |
| Finished At  | datetime | Yes      | When the run finished. Default: 0001-01-01 00:00:00+00:00. |
| Failed Tests | integer  | No       | How many tests failed.                                     |

**Outputs**

| Field        | Type     | Description            |
| ------------ | -------- | ---------------------- |
| Monitor ID   | string   | The monitor that ran.  |
| Status       | string   | The run result.        |
| Finished At  | datetime | When the run finished. |
| Failed Tests | integer  | How many tests failed. |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/postman.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
