Programmatically manage your Postman assets with the Postman API

The Postman API Platform enables you to create a wide range of resources that help you build and use APIs, such as:

• Workspaces: Contain assets you can share with your internal and external teams.
• Collections: Let you organize requests that share a common purpose.
• Environments: Include sets of scoped variables you can use in your requests.
• APIs: Define different standards, such as OpenAPI, GraphQL, or gRPC.
• Mock servers: Simulate the behavior of real API servers by accepting requests and returning responses.
• Monitors: Run requests from the Postman cloud on a schedule you define.

You can manually manage these Postman resources—as well as users, permissions, and Flows—in the Postman desktop app or the Postman web app. You can also use the Postman API to manage these resources programmatically, which enables you to automate many API-related workflows. In this blog post, we’ll walk through some of the features the Postman API has to offer.

Endpoints available to all plans

The following endpoints are available to all users, regardless of their Postman plan.

Workspaces

You can manage your Postman workspaces with the workspaces endpoints. These endpoints enable you to create temporary workspaces to test, which you can then delete when you’re finished. This helps you keep a clean workspace. You can also save a backup of another workspace or specific resources (such as collections or APIs) using the Postman API.

Collections

The collections endpoints enable you to manage your collections programmatically. These endpoints facilitate standard CRUD (Create, Read, Update, and Delete) operations, but they also simplify collection-related workflows. These endpoints include:

• The update part of a collection endpoint lets you make partial changes to a collection. You can modify the name, description, authentication, variables, and events (scripts).
• The items endpoints allow you to perform CRUD operations on individual requests, folders, and responses without having to use PUT on the entire collection. When a collection is too large, performing PUT on the entire collection is costly—and prone to failure.
• The transfers endpoints let you move collection items between different collections or folders. You can also use these endpoints to change the order of folders in a collection.
• The forks endpoints let you programmatically create and merge collection forks.

In addition, you can create a collection from an OpenAPI definition, and vice versa:

• The transform collection to OpenAPI endpoint returns an OpenAPI definition of the given collection ID. You can find out more about this endpoint in our previous “Creating an OpenAPI definition from a collection with the Postman API” blog post.
• The import an OpenAPI definition endpoint lets you use an OpenAPI definition to create a collection.

This functionality is significant because if you can automatically generate a collection from your source code or API definition, you can then automatically sync it with Postman. All other resources that depend on that collection, such as monitors or mock servers, will also see the updated requests and responses.

Variables and environments

There are three different types of variables in Postman, and their values can be changed programmatically with the Postman API. These variable types are:

• Global variables: These variables are available throughout a workspace and can be managed with the global variables endpoints.
• Environment variables: These variables enable you to scope your work to different environments, such as local development, testing, or production. They can be managed with the environments endpoints. Learn more in our “Manage your Postman environments with the Postman API” blog post.
• Collection variables: These variables are available throughout the requests in a collection, and they can be managed with the update part of a collection endpoint.

APIs

The APIs endpoints let you perform simple CRUD operations on your APIs. You can also use them to:

• Modify your API definition with its schema.
• Programmatically create and publish new versions of your API with the version endpoints.
• Manage the collections attached to an API—and sync it automatically—with the API collection endpoints.

These endpoints can be integrated with your CI/CD systems, and they can be used to automate the publication of new API versions. You can find out more about this set of endpoints in our previous “Automate API versioning with the Postman API and GitHub actions” blog post.

Mock servers

Postman mock servers are based on collections. You can change a collection’s behavior with the collections endpoints, which will also change the mock server’s behavior. You can also use the mocks endpoints to perform CRUD operations on your mock servers, or to:

• Set a mock server as public or private.
• Get the list of calls a mock server has received.
• Set server responses for 5XX errors.

You can learn more about the mocks endpoints in our previous “End-to-end testing best practices with Postman mock servers” blog post.

Monitors

The monitors endpoints enable you to programmatically run collections on a schedule or in response to specific events in your CI/CD pipelines. The /monitors endpoints allow you to:

• Run a monitor synchronously.
• Create and run a webhook, which is a special monitor that runs a collection.

Learn more about these endpoints in our “How to run a monitor with the Postman API” blog post.

User and usage information

The Postman API provides the Get authenticated user (/me) endpoint, which enables you to get data on your API usage and check how many requests you can perform until the end of the month.

APIs for Enterprise or Professional plans

Some API endpoints are only available for Enterprise or Professional plan users. These endpoints include:

Private API Network

The Postman API Private Network is a central directory of workspaces, collections, and APIs that your team uses internally. These endpoints let you programmatically manage your Private API Network elements. You can also get all requests to add elements and approve or reject them with the API. This enables you to automate your team’s internal documentation management, integrate it with your CI/CD pipeline, and ensure that the documentation is always up-to-date.

Tags

The tags endpoints let you manage your Postman tags programmatically. You can use these endpoints to add or remove tags from Postman collections, APIs, and workspaces. Additionally, the Get elements by tag endpoint lets you get all Postman elements that match the given tag—and then operate on them programmatically. Learn more about these endpoints in our “Manage element tags programmatically with the Postman API” blog post.

Secret Scanner

The Secret Scanner endpoints, which programmatically provide the same functionality as the Secret Scanner dashboard, allow Enterprise Ultimate customers to manage secrets detected by the Postman Secret Scanner. Use these endpoints to:

• Search detected secrets (paginated).
• Find the location of a detected secret.
• Update the resolution status of a detected secret.

These endpoints enable you to build automatic notification systems, or to programmatically resolve detected secrets.

SCIM user management

Postman supports SCIM (System for Cross-domain Identity Management), which lets you automate the provisioning of your team. You can deploy Postman at scale across your organization and control access to it with your identity provider. The Postman API exposes several SCIM endpoints to automatically provision users and groups.

API security and governance

The API security endpoints let you manage your API’s security by running security checks and validating your API governance rules. For example, you can use the API definition security validation endpoint to validate an OpenAPI definition. If everything is OK, you can use it to publish a new version of your API.

Audit logs

The audit logs endpoints let you monitor and analyze your Professional or Enterprise Postman teams. Team admins can review audit logs, filter by specific criteria, and get information about:

• When users were added to, removed from, or invited to your team.
• Which user performed a specific action—and when they did so.

Conclusion

The Postman API offers a wide range of endpoints to manage your Postman resources programmatically and automate organizational processes. How would you use the Postman API to help automate your development workflow? Share your use cases in the comments!