@postman/api-sdk

v1.44.1

Published

9 days ago

The Postman API enables you to programmatically access data stored in your Postman account. For a comprehensive set of examples of requests and responses, see the [**Postman API** collection](https://www.postman.com/postman/workspace/postman-public-works

0High
0Medium
0Low

postman-admin

aravindrajr

typescript sdk api client

PostmanApi TypeScript SDK 1.44.1

Welcome to the PostmanApi SDK documentation. This guide will help you get started with integrating and using the PostmanApi SDK in your project.

Versions

SDK version: 1.44.1

About the API

The Postman API enables you to programmatically access data stored in your Postman account.

For a comprehensive set of examples of requests and responses, see the Postman API collection.

Note:

Certain endpoints may be unavailable depending on your region and/or Postman plan.

Getting started

You can get started with the Postman API by creating a copy of this definition in your workspace.

EU users

For users in the EU with Enterprise plans, the Postman API uses the http://api.eu.postman.com subdomain. This is available in the definition's list of servers. You can change this by selecting the http://api.eu.postman.com subdomain in the Server dropdown list below.

About the Postman API

You must use a valid API Key to send requests to the API endpoints.
The API has rate and usage limits.
The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources.
The API returns requests responses in JSON format.
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. The POST method implies you want to save something new to Postman.
For all requests, API calls respond with their corresponding HTTP status codes. In the Postman client, the status code also provides help text that details the possible meaning of the response code.

IDs and UIDs

All items in Postman, such as collections, workspaces, and APIs, have IDs and UIDs:

An ID is the unique ID assigned to a Postman item. For example, ec29121c-5203-409f-9e84-e83ffc10f226.
The UID is the full ID of a Postman item. This value is the item's unique ID concatenated with the user ID. For example, in the 12345678-ec29121c-5203-409f-9e84-e83ffc10f226 UID, where 12345678 is the user's ID and ec29121c-5203-409f-9e84-e83ffc10f226 is the item's ID.

Enum values

Any documented enum values should be considered partial lists and may change over time.

403 response for unavailable features

Depending on your region and/or Postman plan, some endpoints will return an HTTP 403 Forbidden response with the "This feature isn't available in your region." detail.

503 response

An HTTP 503 Service Unavailable response from our servers indicates there is an unexpected spike in API access traffic. The server is usually operational within the next five minutes.

If the outage persists or you receive any other form of an HTTP 5XX error, contact support.

Authentication

Postman uses API keys for authentication. The API key tells the API server that the request came from you. Everything that you have access to in Postman is accessible with your API key. You can generate a Postman API key in the API keys section of your Postman account settings.

You must include an API key in each request to the Postman API with the X-API-Key request header. In Postman, you can store your API key as a vault secret or an environment variable. The Postman API collection will use it to make API calls.

SCIM authentication

While all other endpoints in this collection require a Postman API key, the SCIM endpoints require a SCIM API key.

Authentication error response

If an API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.

Rate and usage limits

API access rate limits apply at a per-user basis in unit time. The limit is 300 requests per minute.

Postman Monitors, as well as the GET /collections, GET /workspaces, and GET /workspaces/{id} endpoints have a rate limit of 10 calls in 10 seconds.
Workspace updates endpoints have a rate limit of 20 requests per minute per user.
The POST /service-account-tokens endpoint has a rate limit of 10 requests per 10 second window per user.

Depending on your plan, you may also have usage limits. Every API response includes headers to help you identify the status of your use limits. For more information, see Track Postman API call limits.

When you reach your rate or usage limits, the API returns the following HTTP 429 Too Many Requests status code with one of the following error responses:

rateLimited — Rate limits reached. The response returns the time after which you can resume calls to the Postman API. The response header also includes the X-RateLimit-RetryAfter and Retry-After responses when you go over your limit, which returns the seconds remaining until you can make another request.
serviceLimitExhausted — Postman API service limits reached. You will need to contact your Postman Team Admin for assistance.

Support

For help regarding accessing the Postman API, you can:

Visit Postman Support or our Community and Support sites.
Reach out to the Postman community.
Submit a help request to Postman support.

Policies

Setup & Configuration

Supported Language Versions

This SDK is compatible with the following versions: TypeScript >= 4.8.4

Installation

To get started with the SDK, we recommend installing using npm or yarn:

npm install @postman/api-sdk

yarn add @postman/api-sdk

Authentication

Basic Authentication

The PostmanApi API uses Basic Authentication.

You need to provide your username and password when initializing the SDK.

Setting the Username and Password

When you initialize the SDK, you can set the username and password as follows:

const sdk = new PostmanApi({ username: 'YOUR_USERNAME', password: 'YOUR_PASSWORD' });

If you need to set or update the username and password after initializing the SDK, you can use:

const sdk = new PostmanApi();
sdk.username = 'YOUR_USERNAME';
sdk.password = 'YOUR_PASSWORD';

API Key Authentication

The PostmanApi API uses API keys as a form of authentication. An API key is a unique identifier used to authenticate a user, developer, or a program that is calling the API.

Setting the API key

When you initialize the SDK, you can set the API key as follows:

const sdk = new PostmanApi({ apiKey: 'YOUR_API_KEY' });

If you need to set or update the API key after initializing the SDK, you can use:

const sdk = new PostmanApi();
sdk.apiKey = 'YOUR_API_KEY';

Setting a Custom Timeout

You can set a custom timeout for the SDK's HTTP requests as follows:

const postmanApi = new PostmanApi({ timeout: 10000 });

Sample Usage

Below is a comprehensive example demonstrating how to authenticate and call a simple endpoint:

import { PostmanApi } from '@postman/api-sdk';

(async () => {
  const postmanApi = new PostmanApi({
    apiKey: 'YOUR_API_KEY',
  });

  const data = await postmanApi.billing.getAccounts();

  console.log(data);
})();

Services

The SDK provides various services to interact with the API.

Models

The SDK includes several models that represent the data structures used in API requests and responses. These models help in organizing and managing the data efficiently.

| Name | Description | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AccountInformation | Information about the account. | | InvoicesSlots | Information about the team's slots. | | ErrorTypeTitleDetailStatus | | | GetAuditLogEventActionsClientErrorResponse | | | CreateApiClientErrorResponse | | | GetAccountInvoices | | | AccountInvoice | Information about the invoice. | | InvoicesTotal | Information about the invoice's total billed amount. | | InvoicesLinks | A JSON API spec object containing hypermedia links. | | BillingAccountStatus | | | GetAnalyticsData | | | AnalyticsDataSummary | | | AnalyticsDataObject | Data analytics information. | | GetAnalyticsDataSchema | | | GetAnalyticsDataColumnsData | | | PaginationData | Information about the response pagination. | | AnalyticsDataPartnerEngagementFunnel | | | PartnersEngagementPartnersData | Information about partner users and their activity. | | PartnersEngagementWorkspaceVisits | Information about partner users' workspace visits. | | PartnersEngagementCollectionViews | Information about partner users' views of collections in a workspace. | | PartnersEngagementRequestsSent | Information about requests sent by partner users. | | PartnersEngagementSuccessfulRequestsSent | Information about partner users' successful request calls in a workspace. | | AnalyticsResource | | | AnalyticsMetrics | | | AnalyticsView | | | AnalyticsDuration | | | AnalyticsUserType | | | AnalyticsEntityType | | | ErrorTypeTitleDetailStatus | | | ErrorTypeTitleDetailStatusInstance | | | GetAnalyticsMetadata | | | AnalyticsMetadataResourceData | Information about the resource. | | AnalyticsMetadataMetricsData | Information about the resource's metric. | | AnalyticsMetadataWithParametersAndResponseData | Detailed information about the resource including its metrics, parameters, and response schema. | | GetAnalyticsMetadataResourceMetricsDataDetailed | Information about the resource's metric. | | GetAnalyticsMetadataResourceMetricsDataDetailedParameters | Information about the metric's parameters. | | GetAnalyticsMetadataResourceMetricsDataDetailedParametersView | Information about the view parameter. | | GetAnalyticsMetadataResourceMetricsDataDetailedParametersFiltersData | Information about the filter. | | GetAnalticsMetadataPaginationData | Information about the metric's pagination parameters. | | GetAnalyticsMetadataResourceMetricsDataDetailedResponse1 | Information about the metric's response parameters. | | GetAnalyticsMetadataResourceMetricsDataDetailedData | Information about the metric's detailed parameter. | | GetAnalyticsMetadataResourceMetricsDataSummaryData | Information about the metric's summary parameter. | | GetApiCatalogDiscoveryServices | | | GetApiCatalogDiscoveryMetaData | The response's meta information for paginated results. | | GetApiCatalogServiceData1 | Information about the discovered service. | | DiscoveryServicesSource | | | ErrorTypeStatusTitleDetailErrors | | | ApiCatalogErrorPathMessage | Information about the error. | | ErrorTypeTitleDetailStatus | | | PostApiCatalogDiscoveryServicesResponse | | | PostApiCatalogDiscoveryServicesServiceData | Information about a discovered service. | | PostApiCatalogDiscoveryServicesResponseMetaData | The operation's metadata summary. | | PostApiCatalogDiscoveryServices | | | PostApiCatalogDiscoveryServiceData | Information about the discovered service. | | PostApiCatalogDiscoveryServicesApiDefinitionData | The API definition (specification) for the service. If you pass this with the endpoints array, this object is given preference and endpoints is ignored. | | ApiCatalogDiscoveryServiceEndpointsData | Information about a service's endpoint. | | PostApiCatalogDiscoveryServicesProviderMetadataData | Additional metadata from the discovery source provider. | | GetApiCatalogDiscoveryService | Information about the discovered service. | | ApiCatalogDiscoveryServicesProviderMetadata | Additional metadata from the discovery source provider. | | GetApiCatalogDiscoveryServiceApiDefinitionData | The API definition associated with the service. | | GetApiCatalogServices | | | ApiCatalogServiceMetadataTimeRangeData | The time window for the returned data. | | ApiCatalogServiceServiceData | Information about the service. | | GetApiCatalogService | | | GetApiCatalogServiceTrafficData | Information about traffic and performance within the time window. If there's no traffic data, this returns a null value. | | GetApiCatalogServiceComplianceData | Information about compliance and governance. | | GetApiCatalogServiceEntityCountData | Information about the workspace's entities. | | GetApiCatalogServiceOwnerData | The service's owner. If no owner is assigned, this returns a null value. | | GetApiCatalogServiceEndpoints | | | GetApiCatalogServiceMonitorRuns | | | ApiCatalogServiceCollectionData | Information about the collection. | | ApiCatalogServiceEnvironmentData | Information about the environment. | | ApiCatalogServicePerformanceData | Information about the response time range across all requests in the run. | | ApiCatalogServiceStatusFilter | | | GetApiCatalogServiceSpecificationLints | | | ApiCatalogServiceSpecLintSeverityFilter | | | GetApiCatalogServiceCiRuns | | | GetApiCatalogSystemEnvironments | | | ApiCatalogSystemEnvironmentsMetaData | The response's meta information for paginated results. | | ApiCatalogSystemEnvironmentsFiltersData | The applied filters, if any. | | ApiCatalogSystemEnvironmentData | Information about the system environment. | | CreateApiCatalogSystemEnvironmentResponse | | | PostPatchApiCatalogSystemEnvironmentData | Information about the system environment. | | CreateApiCatalogSystemEnvironment | | | GetApiCatalogSystemEnvironment | | | UpdateApiCatalogSystemEnvironmentResponse | | | UpdateApiCatalogSystemEnvironment | | | GetApiCatalogSystemEnvironmentAssociations | | | GetApiCatalogSystemEnvironmentAssociationsData | Information about the workspace-environment association. | | AddApiCatalogSystemEnvironmentAssociationsResponse | | | AddApiCatalogSystemEnvironmentAssociationsMetaData | The response's meta information for paginated results. | | AddApiCatalogSystemEnvironmentAssociationsData | Information about the associated workspace environment. | | AddApiCatalogSystemEnvironmentAssociations | | | RemoveApiCatalogSystemEnvironmentAssociationsResponse | | | RemoveApiCatalogSystemEnvironmentAssociationsMetaData | The response's meta information for paginated results. | | RemoveApiCatalogSystemEnvironmentAssociationsData | Information about the associated workspace environment. | | RemoveApiCatalogSystemEnvironmentAssociations | | | GetApIs | Information about the API schema. | | ErrorTypeTitleDetailStatus | | | GetAuditLogEventActionsClientErrorResponse | | | CreateApiClientErrorResponse | | | Api404Error2 | | | ApiCreated |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

PostmanApi TypeScript SDK 1.44.1

Versions

About the API

Getting started

EU users

About the Postman API

IDs and UIDs

Enum values

403 response for unavailable features

503 response

Authentication

SCIM authentication

Authentication error response

Rate and usage limits

Support

Policies

Table of Contents

Setup & Configuration

Supported Language Versions

Installation

Authentication

Basic Authentication

Setting the Username and Password

API Key Authentication

Setting the API key

Setting a Custom Timeout

Sample Usage

Services

Models