Postman API

OpenAPI apis-guru developer_tools

The Postman API allows you to programmatically access data stored in Postman account with ease.

The easiest way to get started with the API is to click the fork button to fork this collection to your own workspace and use Postman to send requests.

Overview

You need a valid to send requests to the API endpoints. You can get your key from the .
The API has an access applied to it.
The Postman API will only respond to secured communication done over HTTPS. HTTP requests will be sent a 301 redirect to corresponding HTTPS resources.
Response to every request is sent in . In case the API request results in an error, it is represented by an "error": {} key in the JSON response.
The request method (verb) determines the nature of action you intend to perform. A request made using the GET method implies that you want to fetch something from Postman, and POST implies you want to save something new to Postman.
The API calls will respond with appropriate for all requests. Within Postman Client, when a response is received, the status code is highlighted and is accompanied by a help text that indicates the possible meaning of the response code. A 200 OK indicates all went well, while 4XX or 5XX response codes indicate an error from the requesting client or our API servers respectively.
Individual resources in your Postman Account is accessible using its unique id (uid). The uid is a simple concatenation of the resource owner's user-id and the resource-id. For example, a collection's uid is {{owner_id}}-{{collection_id}}.

Authentication

An API Key is required to be sent as part of every request to the Postman API, in the form of an X-Api-Key request header.

If you do not have an API Key, you can easily generate one by heading over to the .

An API Key tells our API server that the request it received came from you. Everything that you have access to in Postman is accessible with an API Key that is generated by you.

For ease of use inside Postman, you could store your API key in an called postman_api_key and this will automatically use it to make API calls.

API Key related error response

If an API Key is missing, malformed, or invalid, you will receive a 401 Unauthorised response code and the following JSON response:

Using the API Key as a query parameter

Every request that accepts API Key as X-Api-Key request header, also accepts the key when sent as apikey URL query parameter.

API key sent as part of the header has a higher priority in case you send the key using both request header and query parameter.

Rate Limits

API access rate limits are applied at a per-key basis in unit time. Access to the API using a key is limited to 60 requests per minute. In addition, every API response is accompanied by the following set of headers to identify the status of your consumption.

Header	Description
`X-RateLimit-Limit`	The maximum number of requests that the consumer is permitted to make per minute.
`X-RateLimit-Remaining`	The number of requests remaining in the current rate limit window.
`X-RateLimit-Reset`	The time at which the current rate limit window resets in UTC epoch seconds.

Once you hit the rate limit, you will receive a response similar to the following JSON, with a status code of 429 Too Many Requests.

Support

For help regarding accessing the Postman API, feel free to discuss it in our . You can also drop in a line at .

In the event you receive a 503 response from our servers, it implies that we have hit an unexpected spike in API access traffic and would usually be operational within the next 5 minutes. If the outage persists, or your receive any other form of 5XX error, kindly let us know.

Terms of Use

For information on API terms of use and privacy, refer to our terms at and our privacy policy at .

API Reference

Homepage: https://api.apis.guru/v2/specs/getpostman.com/1.20.0.json
Provider: getpostman.com
OpenAPI version: 3.0.3
Spec (JSON): https://api.apis.guru/v2/specs/getpostman.com/1.20.0/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/getpostman.com/1.20.0/openapi.yaml

Tools (59)

Extracted live via the executor SDK.

api.createApi

This call creates a new API with a default API Version.
Request body should contain an api object which should atleast have a property name.
Response contains an api object with all the details related to the created API, namely, id, name, summary, description, etc.

Requires as X-Api-Key request header or apikey URL query parameter.

api.createApiVersion

This call creates a new API version in the specified API.

Request body should contain a version object which should have fields:

name

Required. Name of the API Version

source

If specified, it will copy the contents of the specified api version to create a new api verison.

Response contains a version object with all the details related to the created API Version, namely, id, name, api.

Requires as X-Api-Key request header or apikey URL query parameter.

api.createCollectionFromSchema
This call creates a collection and links it to an API as one or multiple relations.
Request body requires two keys:
- name - Name of the collection to be created.
- relations - A list of relation(s) to be created.
The allowed relation types are contracttest, integrationtest, testsuite, and documentation.

Requires as X-Api-Key request header or apikey URL query parameter.
api.createRelations

This call allows you to add existing Postman entities as new relations to an API. The request body should contain the relations to be created along with an array of entity IDs.
Relation Entity ID type
contracttest Collection UIDs
integrationtest Collection UIDs
documentation Collection UIDs
testsuite Collection UIDs
environment Environment UIDs
mock Mock IDs
monitor Monitor IDs

Requires as X-Api-Key request header or apikey URL query parameter.
api.createSchema
This call creates a new schema.
Request body should contain a schema object which should atleast have these properties with string values:
- type: Allowed types are openapi3, openapi2, openapi1, raml and graphql.
- language : Allowed languages are json and yaml for OpenAPI and RAML schema types. GraphQL schema type accepts only graphql language.
- schema: Optional. If passed, must be the content of the schema as a string.
Response contains a schema object with all the details related to the created schema, namely, id, language, type etc.

Requires as X-Api-Key request header or apikey URL query parameter.
api.deleteAnApi

This call deletes an existing API having the specified id.
Response contains an api object with id of the API which was deleted.

Requires as X-Api-Key request header or apikey URL query parameter.
api.deleteAnApiVersion

This call deletes an existing API Version having the specified id.
Response contains an version object with id of the API Version which was deleted.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getAllApIs

This call fetches all the APIs present in the specified workspace
Response contains an array named apis which would contain all the details of APIs present in the workspace.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getAllApiVersions

This call fetches details about the all the API Versions in the specified API.
The response will contain an array versions object which would be a list of all the API Version along with their details.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getAnApiVersion

This call fetches details about the specified API Version.
The response will contain a version object which would contain all the details of the API Version.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getContractTestRelations

This call fetches all the relations by type which are linked to the specified API version along with their details.
The response will contain an array with key {{relationType}}. Each of the item will consist of all the details related each of the relation.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getDocumentationRelations

This call fetches all the relations by type which are linked to the specified API version along with their details.
The response will contain an array with key {{relationType}}. Each of the item will consist of all the details related each of the relation.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getEnvironmentRelations

This call fetches all the relations by type which are linked to the specified API version along with their details.
The response will contain an array with key {{relationType}}. Each of the item will consist of all the details related each of the relation.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getIntegrationTestRelations

This call fetches all the relations by type which are linked to the specified API version along with their details.
The response will contain an array with key {{relationType}}. Each of the item will consist of all the details related each of the relation.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getLinkedRelations

This call fetches all the relations which are linked to the specified API version along with their details.
The response will contain a relations object which lists all the relation types which are linked to the API version. Each of the relation type will be an object which details the relations of this type.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getMonitorRelations

This call fetches all the relations by type which are linked to the specified API version along with their details.
The response will contain an array with key {{relationType}}. Each of the item will consist of all the details related each of the relation.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getSchema

This call fetches a single schema having the specified id.
Response contains a schema object with all the details related to the schema, namely, id, language, type, schema etc.

Requires as X-Api-Key request header or apikey URL query parameter.
api.getTestSuiteRelations

This call fetches all the relations by type which are linked to the specified API version along with their details.
The response will contain an array with key {{relationType}}. Each of the item will consist of all the details related each of the relation.

Requires as X-Api-Key request header or apikey URL query parameter.
api.singleApi

This call fetches a single API having the specified id.
Response contains an api object with all the details related to the queried API, namely, id, name, summary, description etc.

Requires as X-Api-Key request header or apikey URL query parameter.
api.syncRelationsWithSchema

This call allows you to keep the relation in sync with the API schema.

Requires as X-Api-Key request header or apikey URL query parameter.
api.updateAnApi

This call updates an existing API .
Request body should contain an api object which should have the fields to be updated. Only name, summary and description fields can be edited for an API.
Response contains an api object with all the details related to the created API, namely, id, name, summary, description etc.

Requires as X-Api-Key request header or apikey URL query parameter.
api.updateAnApiVersion

This call updates an existing API Version.
Request body should contain a version object with the fields which need to be updated. Only field which can be updated is name.
Response contains a version object with all the details related to the created API Version, namely, id, name, api etc.

Requires as X-Api-Key request header or apikey URL query parameter.
api.updateSchema
This call updates an existing schema.
Request body should contain a schema object which should atleast have these properties with string values:
- type: Allowed types are openapi3, openapi2, openapi1, raml and graphql.
- language : Allowed languages are json and yaml for OpenAPI and RAML schema types. GraphQL schema type accepts only graphql language.
- schema: Optional. If passed, must be the content of the schema as a string.
Response contains a schema object with all the details related to the created schema, namely, id, language, type etc.

Requires as X-Api-Key request header or apikey URL query parameter.
collections.allCollections

The /collections endpoint returns a list of all that are accessible by you. The list includes your own collections and the collections that you have subscribed to.
The response contains an array of collection information containing the name, id, owner and uid of each collection.

Requires as X-Api-Key request header or apikey URL query parameter.
collections.createAFork

This endpoint allows you to create a fork from an existing collection.
On successful creation of the collection, the response returns the collection name, id, uid along with fork information.
You can also specify the context of a workspace to fork a collection in by passing the workspace as a query param.

Requires as X-Api-Key request header or apikey URL query parameter.
collections.createCollection

This endpoint allows you to create collections using the Postman Collection v2 format. For more information about the v2 schema, check the format .
On successful creation of the collection, the response returns the collection name, id and the uid.
You can also specify the context of a workspace to create a collection in directly by passing the workspace as a query param.

Requires as X-Api-Key request header or apikey URL query parameter.
collections.deleteCollection

This endpoint allows you to delete an existing collection.
On successful deletion of the collection, the response returns the id and uid.

Requires as X-Api-Key request header or apikey URL query parameter.
collections.mergeAFork

This endpoint allows you to merge a forked collection back to its destination collection.
On successful creation of the collection, the response returns the collection name, id and uid.
You need to specify the fork UID (as source) and destination collection UID (as destination) in the request body.
Optionally, you can also specify the merge strategy as either deleteSource or updateSourceWithDestination. Following is an explanation of the merge strategies

Merge Strategy Behaviour
deleteSource Forked collection is deleted after merging
updateSourceWithDestination Forked collection is up to date with changes in destination collection
If the collections cannot be merged (due to conflicts), appropriate error messages will be returned.

Requires as X-Api-Key request header or apikey URL query parameter.
collections.singleCollection

Access the contents of a collection that is accessible to you using its unique id (uid).

Requires as X-Api-Key request header or apikey URL query parameter.
collections.updateCollection

This endpoint allows you to update an existing collection using the Postman Collection v2 format. For more information about the v2 schema, check the format .
On successful updation of the collection, the response returns the collection name, id and uid.

Requires as X-Api-Key request header or apikey URL query parameter.

Note: Please be careful when trying to update the collection, as the existing collection will be replaced by the request body.
environments.allEnvironments

The /environments endpoint returns a list of all that belong to you..
The response contains an array of environments' information containing the name, id, owner and uid of each environment.

Requires as X-Api-Key request header or apikey URL query parameter.

Relation	Entity ID type
contracttest	Collection UIDs
integrationtest	Collection UIDs
documentation	Collection UIDs
testsuite	Collection UIDs
environment	Environment UIDs
mock	Mock IDs
monitor	Monitor IDs

Merge Strategy	Behaviour
deleteSource	Forked collection is deleted after merging
updateSourceWithDestination	Forked collection is up to date with changes in destination collection

environments.createEnvironment

A sample body is added to the request that conforms to the following JSON schema:

json

{  "type": "object",  "properties": {    "environment": {      "type": "object",      "properties": {        "name": {              "type": "string",              "maxLength": 254,              "minLength": 1            },        "values": {          "type": "array",          "maxItems": 100,          "additionalItems": false,          "items": {              "type": "object",              "properties": {                "key": {                  "type": "string",                  "maxLength": 254                  "minLength": 1                },                "value": { "type": "string" },                "enabled": { "type": "boolean" }              },              "required": ["key", "value"]            }        }      },      "required": ["name"]    }  },  "required": ["environment"]}

On successful creation of the environment, the API returns the environment name and id.

You can also specify the context of a workspace to create an environment in directly by passing the workspace as a query param.

Requires as X-Api-Key request header or apikey URL query parameter.

{  "type": "object",  "properties": {    "environment": {      "type": "object",      "properties": {        "name": {              "type": "string",              "maxLength": 254,              "minLength": 1            },        "values": {          "type": "array",          "maxItems": 100,          "additionalItems": false,          "items": {              "type": "object",              "properties": {                "key": {                  "type": "string",                  "maxLength": 254                  "minLength": 1                },                "value": { "type": "string" },                "enabled": { "type": "boolean" }              },              "required": ["key", "value"]            }        }      },      "required": ["name"]    }  },  "required": ["environment"]}

environments.deleteEnvironment

This endpoint allows you to delete a single environment based on an environment's unique uid.

Requires as X-Api-Key request header or apikey URL query parameter.
environments.singleEnvironment

Access the contents of an environment that is accessible to you using its unique id (uid).

Requires as X-Api-Key request header or apikey URL query parameter.

environments.updateEnvironment

This endpoint replaces an existing environment.

A sample body is added to the request that conforms to the following JSON schema:

json

{	"type": "object",	"properties": {		"environment": {			"type": "object",			"properties": {				"name": {					"type": "string",					"maxLength": 254,					"minLength": 1				},				"values": {					"type": "array",					"maxItems": 100,					"additionalItems": false,					"items": {						"type": "object",						"properties": {							"key": {								"type": "string",								"maxLength": 254,								"minLength": 1							},							"value": {								"type": "string",								"maxLength": 254,								"minLength": 1							},							"type": {								"type": "string"							},							"enabled": {								"type": "boolean"							}						},						"required": [							"key",							"value"						]					}				}			}		}	},	"required": [		"environment"	]}

On successful updation of the environment, the API returns the environment name and id.

Requires as X-Api-Key request header or apikey URL query parameter.

{	"type": "object",	"properties": {		"environment": {			"type": "object",			"properties": {				"name": {					"type": "string",					"maxLength": 254,					"minLength": 1				},				"values": {					"type": "array",					"maxItems": 100,					"additionalItems": false,					"items": {						"type": "object",						"properties": {							"key": {								"type": "string",								"maxLength": 254,								"minLength": 1							},							"value": {								"type": "string",								"maxLength": 254,								"minLength": 1							},							"type": {								"type": "string"							},							"enabled": {								"type": "boolean"							}						},						"required": [							"key",							"value"						]					}				}			}		}	},	"required": [		"environment"	]}

import.importExportedData

This endpoint allows you to import your exported Postman data. For more information about how you can export your data, refer
On successful imports, the response will be an array with Each element contaning id, name and uid of entities created.
Note: Refer to examples for different scenarios.

Requires as X-Api-Key request header.
import.importExternalApiSpecification
This endpoint allows you to import external API specifications into Postman.
Currently, this endpoint only supports the specification, for which the importType will be openapi.
On a successful import, the response will be an array with each element contaning id, name and uid of entities created.
Supported types:
- string
- json
- file
The input parameter should be defined based on the type.

To import a file, request body must be form-data with type param set to file.

Note: Refer to examples for different scenarios.

Requires as X-Api-Key request header.
mocks.allMocks

This endpoint fetches all the mocks that you have created.

Requires as X-Api-Key request header or apikey URL query parameter.
mocks.createMock

This endpoint allows you to create a mock on a collection. You can also provide an environment UID to resolve any environment variables in the collection.
You can also specify the context of a workspace to create a mock in directly by passing the workspace as a query param.

Requires as X-Api-Key request header or apikey URL query parameter.
mocks.deleteMock

This endpoint allows you to delete an existing mock using its uid.

Requires as X-Api-Key request header or apikey URL query parameter.
mocks.publishMock

This endpoint publishes the mock you have created using its uid

Requires as X-Api-Key request header or apikey URL query parameter.
mocks.singleMock

This endpoint fetches you the basic information about a single mock using its uid.

Requires as X-Api-Key request header or apikey URL query parameter.
mocks.unpublishMock

This endpoint unpublishes the mock you have created using its uid

Requires as X-Api-Key request header or apikey URL query parameter.
mocks.updateMock
This endpoint allows you to update a mock you have created using its uid. The endpoint allows you to edit fields,
- name
- environment
- description
- private
- versionTag
Requires as X-Api-Key request header or apikey URL query parameter.
monitors.allMonitors

The /monitors endpoint returns a list of all that are accessible by you.
The response contains an array of monitors information containing the name, id, owner and uid of each monitor.

Requires as X-Api-Key request header or apikey URL query parameter.

monitors.createMonitor

This endpoint allows you to create a monitor.

Some sample cron values are:

Frequency	Cron Pattern
Every 5 minutes	`/5 * * *`
Every 30 minutes	`/30 * * *`
Every Hour	`0 /1 * *`
Every 6 Hours	`0 /6 * *`
Every day at 5pm	`0 17 * * *`
Every Monday at 12pm	`0 12 * * MON`
Every weekday (Monday - Friday) at 6am	`0 6 * * MON-FRI`

Note: Currently, you can only create monitors at some limited schedules. You can head to to see the allowed schedules.

For more information about the format of the timezone value, check this

You can also specify the context of a workspace to create a monitor in directly by passing the workspace as a query param.

Requires as X-Api-Key request header or apikey URL query parameter.

monitors.deleteMonitor

This endpoint can be used to delete an existing monitor using its uid.

Requires as X-Api-Key request header or apikey URL query parameter.
monitors.runAMonitor

This endpoint will run the monitor instantly and wait for the monitor to run completely. It responds with the run results.

Requires as X-Api-Key request header or apikey URL query parameter.
monitors.singleMonitor

This endpoint fetches you basic information about the monitor using its uid.

Requires as X-Api-Key request header or apikey URL query parameter.

monitors.updateMonitor

This endpoint allows you to update a monitor using its uid. Only the monitor name and its schedule can be updated.

Some example cron values are:

Frequency	Cron Pattern
Every 5 minutes	`/5 * * *`
Every 30 minutes	`/30 * * *`
Every Hour	`0 /1 * *`
Every 6 Hours	`0 /6 * *`
Every day at 5pm	`0 17 * * *`
Every Monday at 12pm	`0 12 * * MON`
Every weekday (Monday - Friday) at 6am	`0 6 * * MON-FRI`

Note: Currently, you can only create monitors at some limited schedules. You can head to to see the allowed schedules.

For more information about the format of the timezone value, check this

Requires as X-Api-Key request header or apikey URL query parameter.

user.apiKeyOwner

the /me Postman API endpoint lets you access information about the authenticated user. You can retrieve the authenticated user's username, full name, e-mail address, and any other available information.

Requires as X-Api-Key request header or apikey URL query parameter.
webhooks.createWebhook
Create a webhook that triggers a collection with your custom payload.
You can specify the webhook name and the collection to trigger by using the following attributes of the webhook object on your JSON body:
- name: the name of the webhook that you're creating.
- collection: the ID of the collection that you want to trigger once this webhook is called.
Once created, the webhook URL can be retrieved by accessing the webhookUrl attribute of the webhook object on the response JSON payload.
workspaces.allWorkspaces

The /workspaces endpoint returns a list of all that is accessible by you. The list includes your own workspaces and the workspaces that you have access to.
The response contains an array of collection information containing the name, id, and type of each workspace.

Requires as X-Api-Key request header or apikey URL query parameter.
workspaces.createWorkspace

This endpoint allows you to create a workspace and populate it with entities like collections, environments, mocks and monitors using their uid.
On successful creation of the workspace, the response returns the workspcae name and id.

Requires as X-Api-Key request header or apikey URL query parameter.
workspaces.deleteWorkspace

This endpoint allows you to delete an existing workspace.
On successful deletion of the workspace, the response returns the id.

Requires as X-Api-Key request header or apikey URL query parameter.
workspaces.singleWorkspace

Access the contents of a workspace that is accessible to you using its id (id). Includes the collections, environments, mocks and monitors of that workspace.

Requires as X-Api-Key request header or apikey URL query parameter.
workspaces.updateWorkspace

This endpoint allows you to update a workspace and update it's association to entities like collections, environments, mocks and monitors using their uid.
On successful updation of the workspace, the response returns the workspcae name and id.

Requires as X-Api-Key request header or apikey URL query parameter.

Note : The endpoint expects you to send the desired state of the workspace in terms of the associated entities so be careful when trying to update these entities.
For eg. if your workspace has collections A and B, and in the update call, you send C's uid in the collections array, then A and B would be removed from the workspace and C would be added.
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools