Postman API
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…
Developer tools#openapi#developer-tools
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
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 API Key to send requests to the API endpoints. You can get your key from the integrations dashboard.
- The API has an access rate limit applied to it.
- The Postman API will only respond to secured communication done over HTTPS. HTTP requests will be sent a
301redirect to corresponding HTTPS resources.
- Response to every request is sent in JSON format. 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
GETmethod implies that you want to fetch something from Postman, andPOSTimplies you want to save something new to Postman.
- The API calls will respond with appropriate HTTP status codes 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 OKindicates all went well, while4XXor5XXresponse 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). Theuidis a simple concatenation of the resource owner's user-id and the resource-id. For example, a collection'suidis{{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 Postman Integrations Dashboard.
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 environment variable called postman_api_key and this Collection 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:
{
"error": {
"name": "AuthenticationError",
"message": "API Key missing. Every request requires an API Key to be sent."
}
}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.
{
"error": {
"name": "rateLimitError",
"message": "Rate Limit exceeded. Please retry at 1465452702843"
}
}Support
For help regarding accessing the Postman API, feel free to discuss it in our Discourse Community. You can also drop in a line at [help@getpostman.com](mailto:help@getpostman.com).
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 http://postman.com/legal/terms/ and our privacy policy at https://www.postman.com/legal/privacy-policy/.
API Reference
Endpoints 57
Collections
- GETAll Collections
/collectionsThe /collections endpoint returns a list of all collections that are accessible by you. The list includes your own collections and the collections that you… - POSTCreate Collection
/collectionsThis endpoint allows you to create collections using the Postman Collection v2 format. For more information about the v2 schema, check the format here. On… - POSTCreate a Fork
/collections/fork/:collection_uid?workspace={{workspace_id}}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,… - POSTMerge a Fork
/collections/mergeThis endpoint allows you to merge a forked collection back to its destination collection. On successful creation of the collection, the response returns the… - GETSingle Collection
/collections/:collection_uidAccess the contents of a collection that is accessible to you using its unique id (uid). > Requires <a href="#authentication">API Key</a> as X-Api-Key request… - PUTUpdate Collection
/collections/:collection_uidThis endpoint allows you to update an existing collection using the Postman Collection v2 format. For more information about the v2 schema, check the format… - DELETEDelete Collection
/collections/:collection_uidThis endpoint allows you to delete an existing collection. On successful deletion of the collection, the response returns the id and uid. > Requires <a…
Environments
- GETAll Environments
/environmentsThe /environments endpoint returns a list of all environments that belong to you.. The response contains an array of environments' information containing the… - POSTCreate Environment
/environmentsA sample body is added to the request that conforms to the following JSON schema: { "type": "object", "properties": { "environment": { "type": "object",… - GETSingle Environment
/environments/:environment_uidAccess the contents of an environment that is accessible to you using its unique id (uid). > Requires <a href="#authentication">API Key</a> as X-Api-Key… - PUTUpdate Environment
/environments/:environment_uidThis endpoint replaces an existing environment. A sample body is added to the request that conforms to the following JSON schema: { "type": "object",… - DELETEDelete Environment
/environments/:environment_uidThis endpoint allows you to delete a single environment based on an environment's unique uid. > Requires <a href="#authentication">API Key</a> as X-Api-Key…
Mocks
- GETAll Mocks
/mocksThis endpoint fetches all the mocks that you have created. > Requires <a href="#authentication">API Key</a> as X-Api-Key request header or apikey URL query… - POSTCreate Mock
/mocksThis 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… - GETSingle Mock
/mocks/:mock_uidThis endpoint fetches you the basic information about a single mock using its uid. > Requires <a href="#authentication">API Key</a> as X-Api-Key request… - PUTUpdate Mock
/mocks/:mock_uidThis endpoint allows you to update a mock you have created using its uid. The endpoint allows you to edit fields, * name * environment * description * private… - DELETEDelete Mock
/mocks/:mock_uidThis endpoint allows you to delete an existing mock using its uid. > Requires <a href="#authentication">API Key</a> as X-Api-Key request header or apikey URL… - POSTPublish Mock
/mocks/:mock_uid/publishThis endpoint publishes the mock you have created using its uid > Requires <a href="#authentication">API Key</a> as X-Api-Key request header or apikey URL… - DELETEUnpublish Mock
/mocks/:mock_uid/unpublishThis endpoint unpublishes the mock you have created using its uid > Requires <a href="#authentication">API Key</a> as X-Api-Key request header or apikey URL…
Monitors
- GETAll Monitors
/monitorsThe /monitors endpoint returns a list of all monitors that are accessible by you. The response contains an array of monitors information containing the name,… - POSTCreate Monitor
/monitorsThis endpoint allows you to create a monitor. Some sample cron values are: Note: Currently, you can only create monitors at some limited schedules. You can… - GETSingle Monitor
/monitors/:monitor_uidThis endpoint fetches you basic information about the monitor using its uid. > Requires <a href="#authentication">API Key</a> as X-Api-Key request header or… - PUTUpdate Monitor
/monitors/:monitor_uidThis 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: Note:… - DELETEDelete Monitor
/monitors/:monitor_uidThis endpoint can be used to delete an existing monitor using its uid. > Requires <a href="#authentication">API Key</a> as X-Api-Key request header or apikey… - POSTRun a Monitor
/monitors/:monitor_uid/runThis endpoint will run the monitor instantly and wait for the monitor to run completely. It responds with the run results. > Requires <a…
Workspaces
- GETAll workspaces
/workspacesThe /workspaces endpoint returns a list of all workspaces that is accessible by you. The list includes your own workspaces and the workspaces that you have… - POSTCreate Workspace
/workspacesThis endpoint allows you to create a workspace and populate it with entities like collections, environments, mocks and monitors using their uid. On successful… - GETSingle workspace
/workspaces/:workspace_idAccess the contents of a workspace that is accessible to you using its id (id). Includes the collections, environments, mocks and monitors of that workspace.… - PUTUpdate Workspace
/workspaces/:workspace_idThis endpoint allows you to update a workspace and update it's association to entities like collections, environments, mocks and monitors using their uid. On… - DELETEDelete Workspace
/workspaces/:workspace_idThis endpoint allows you to delete an existing workspace. On successful deletion of the workspace, the response returns the id. > Requires <a…
User
- GETAPI Key Owner
/methe /me Postman API endpoint lets you access information about the authenticated user. You can retrieve the authenticated user's username, full name, e-mail…
Import
- POSTImport exported data
/import/exportedThis endpoint allows you to import your exported Postman data. For more information about how you can export your data, refer <a… - POSTImport external API specification
/import/openapiThis endpoint allows you to import external API specifications into Postman. Currently, this endpoint only supports the <a…
API
- GETGet all APIs
/apis?workspace={{workspaceId}}&since={{since}}&until={{until}}&createdBy={{createdBy}}&updatedBy={{updatedBy}}&isPublic={{isPublic}}&name={{name}}&summary={{summary}}&description={{description}}&sort={{sort}}&direction={{direction}}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… - POSTCreate API
/apis?workspace={{workspaceId}}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… - GETSingle API
/apis/:apiIdThis 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,… - PUTUpdate an API
/apis/:apiIdThis 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… - DELETEDelete an API
/apis/:apiIdThis call deletes an existing API having the specified id. Response contains an api object with id of the API which was deleted. > Requires <a… - GETGet All API Versions
/apis/:apiId/versionsThis 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… - POSTCreate API Version
/apis/:apiId/versionsThis call creates a new API version in the specified API. Request body should contain a version object which should have fields: <table> <tr> <td>name</td>… - GETGet an API Version
/apis/:apiId/versions/:apiVersionIdThis 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.… - PUTUpdate an API Version
/apis/:apiId/versions/:apiVersionIdThis 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… - DELETEDelete an API Version
/apis/:apiId/versions/:apiVersionIdThis call deletes an existing API Version having the specified id. Response contains an version object with id of the API Version which was deleted. >… - GETGet contract test relations
/apis/:apiId/versions/:apiVersionId/contracttestThis 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… - GETGet documentation relations
/apis/:apiId/versions/:apiVersionId/documentationThis 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… - GETGet environment relations
/apis/:apiId/versions/:apiVersionId/environmentThis 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… - GETGet integration test relations
/apis/:apiId/versions/:apiVersionId/integrationtestThis 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… - GETGet monitor relations
/apis/:apiId/versions/:apiVersionId/monitorThis 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… - GETGet linked relations
/apis/:apiId/versions/:apiVersionId/relationsThis 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… - POSTCreate relations
/apis/:apiId/versions/:apiVersionId/relationsThis 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… - POSTCreate Schema
/apis/:apiId/versions/:apiVersionId/schemasThis call creates a new schema. Request body should contain a schema object which should atleast have these properties with string values: type: Allowed types… - GETGet Schema
/apis/:apiId/versions/:apiVersionId/schemas/:schemaIdThis 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,… - PUTUpdate Schema
/apis/:apiId/versions/:apiVersionId/schemas/:schemaIdThis call updates an existing schema. Request body should contain a schema object which should atleast have these properties with string values: type: Allowed… - POSTCreate collection from schema
/apis/:apiId/versions/:apiVersionId/schemas/:schemaId/collections?workspace={{workspaceId}}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… - GETGet test suite relations
/apis/:apiId/versions/:apiVersionId/testsuiteThis 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… - PUTSync relations with schema
/apis/:apiId/versions/:apiVersionId/:entityType/:entityId/syncWithSchemaThis call allows you to keep the relation in sync with the API schema. > Requires <a href="#authentication">API Key</a> as X-Api-Key request header or apikey…
Webhooks
- POSTCreate Webhook
/webhooks?workspace={{workspace_id}}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…
API details
- Base URL
https://api.getpostman.com- Authentication
- None declared in the description
- Operations
- 57 operations on 34 pathsGET 23POST 17PUT 9DELETE 8
- Main resources
- API 23Relations 9Collections 7Mocks 7Monitors 6API Version 5Environments 5Workspaces 5Schema 4Import 2
- Response formats
application/json- Description format
- OpenAPI 3.0.3, API version
1.20.0 - Links
- OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Postman API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Postman API collection, without the publisher's secrets.
- Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
- Send a requestPick an endpoint, for example “All Collections” (GET /collections), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Postman API?
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… It is listed under Developer tools and has 57 endpoints.
Who publishes the Postman API?
It is listed from Getpostman's public API description (an OpenAPI document), not published by Getpostman on Swastik Codes. Anyone who controls getpostman.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Postman API?
Requests go to https://api.getpostman.com. Endpoint paths are added to this base URL.
How do I authenticate with the Postman API?
Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.
How many endpoints does the Postman API have?
57 operations on 34 paths (23 GET, 17 POST, 9 PUT, 8 DELETE). The largest groups are API, Relations, Collections, Mocks.
Is forking the Postman API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.