A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Postman API is how an app or AI agent works with a Postman account: listing and editing collections, managing environments and workspaces, reading API definitions, and running mock servers and monitors. Access is granted through a single API key sent in a request header, and that key inherits the exact permissions of the person who created it, so it reaches whatever Postman data that person can see across their teams. Postman does not push events, but the API can create a webhook whose URL triggers a collection run when it is called.
How an app or AI agent connects to Postman determines what it can reach. The main route is the REST API behind an API key, and Postman also runs a first-party MCP server for agents.
The REST API answers at https://api.getpostman.com. Every request carries an API key in the X-API-Key header, and the same base covers collections, environments, workspaces, APIs, mocks, monitors, and the /me endpoint.
Postman's first-party MCP server exposes the Postman API as tools an AI agent can call. The remote server answers at https://mcp.postman.com, with a default minimal tool set at /minimal, a full set of more than 100 tools at /mcp, and a code-focused set at /code, plus an EU host at https://mcp.eu.postman.com. The US server supports OAuth and needs no API key; the EU server uses a Postman API key. The source is at github.com/postmanlabs/postman-mcp-server.
A webhook created through the API returns a URL that, when called, triggers a collection run through a monitor. This is the reverse of an event push: Postman does not notify the app, it gives the app a URL to call when it wants the run to start.
An API key generated from Postman account settings, sent in the X-API-Key header on every request. The key grants access to any Postman data the person who created it has permission for, so it acts as that user across their teams and workspaces. There are no per-endpoint scopes.
The US remote MCP server supports OAuth, so an agent connecting through it does not need to hold a long-lived Postman API key. OAuth is not supported on the EU MCP server, which uses an API key instead.
The Postman API is split into areas an agent can act on, such as collections, environments, workspaces, API definitions, mock servers, and monitors. Each area has its own methods, but all of them are reached through one API key that carries the same access the person behind it has.
List collections, read a single collection, and create, update, or delete collections.
List environments, read a single environment, and create, update, or delete environments.
List workspaces, read a single workspace, and create, update, or delete workspaces.
List the API definitions in a workspace and read a single API definition.
List mock servers and create a mock server from a collection.
List monitors, read a single monitor, and run a monitor on demand.
Create a webhook whose URL triggers a collection run.
Read the authenticated user behind the API key.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CollectionsList collections, read a single collection, and create, update, or delete collections.5 | ||||||
| GET | /collections | List all collections the API key can access, optionally scoped to a workspace. | read | — | Current | |
No per-endpoint scope exists. The key returns whatever collections its owner can see. This endpoint is rate-limited to 10 calls per 10 seconds. Acts oncollection Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 calls / 10 seconds SourceOfficial documentation ↗ | ||||||
| GET | /collections/{collectionId} | Get a single collection's contents, including its requests, folders, and scripts. | read | — | Current | |
No per-endpoint scope exists. Access depends on the key owner's permission on the collection. Acts oncollection Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /collections | Create a collection, optionally inside a chosen workspace. | write | — | Current | |
No per-endpoint scope exists. The key owner needs write access to the target workspace. Acts oncollection Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /collections/{collectionId} | Replace a collection with an updated definition. | write | — | Current | |
No per-endpoint scope exists. The key owner needs write access to the collection. Acts oncollection Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /collections/{collectionId} | Delete a collection. | write | — | Current | |
No per-endpoint scope exists. The key owner needs delete access to the collection. Acts oncollection Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EnvironmentsList environments, read a single environment, and create, update, or delete environments.5 | ||||||
| GET | /environments | List all environments the API key can access. | read | — | Current | |
No per-endpoint scope exists. Returns whatever environments the key owner can see. Acts onenvironment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /environments/{environmentId} | Get a single environment and its variables. | read | — | Current | |
No per-endpoint scope exists. Variable values can include secrets the key owner can read. Acts onenvironment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /environments | Create an environment, optionally in a chosen workspace. | write | — | Current | |
No per-endpoint scope exists. The key owner needs write access to the target workspace. Acts onenvironment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /environments/{environmentId} | Replace an environment with an updated definition. | write | — | Current | |
No per-endpoint scope exists. The key owner needs write access to the environment. Acts onenvironment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /environments/{environmentId} | Delete an environment. | write | — | Current | |
No per-endpoint scope exists. The key owner needs delete access to the environment. Acts onenvironment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkspacesList workspaces, read a single workspace, and create, update, or delete workspaces.5 | ||||||
| GET | /workspaces | List all workspaces the API key can access. | read | — | Current | |
No per-endpoint scope exists. Returns every workspace the key owner is a member of. Rate-limited to 10 calls per 10 seconds. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 calls / 10 seconds SourceOfficial documentation ↗ | ||||||
| GET | /workspaces/{workspaceId} | Get a single workspace, including the resources it contains. | read | — | Current | |
No per-endpoint scope exists. Rate-limited to 10 calls per 10 seconds. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 calls / 10 seconds SourceOfficial documentation ↗ | ||||||
| POST | /workspaces | Create a workspace. | write | — | Current | |
No per-endpoint scope exists. The key owner needs permission to create workspaces in the team. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /workspaces/{workspaceId} | Update a workspace's name, type, or description. | write | — | Current | |
No per-endpoint scope exists. Workspace-update endpoints are rate-limited to 20 requests per minute per user. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit20 requests / minute / user SourceOfficial documentation ↗ | ||||||
| DELETE | /workspaces/{workspaceId} | Delete a workspace and everything inside it. | write | — | Current | |
No per-endpoint scope exists. Deleting a workspace removes the collections, environments, and other resources it holds. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
APIsList the API definitions in a workspace and read a single API definition.2 | ||||||
| GET | /apis | List the API definitions in a workspace (workspaceId is required). | read | — | Current | |
No per-endpoint scope exists. The workspaceId query parameter is required to scope the list. Acts onapi Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /apis/{apiId} | Get a single API definition. | read | — | Current | |
No per-endpoint scope exists. Access depends on the key owner's permission on the API. Acts onapi Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Mock serversList mock servers and create a mock server from a collection.2 | ||||||
| GET | /mocks | List mock servers, returning each one's mockUrl. | read | — | Current | |
No per-endpoint scope exists. Mock servers allow 120 requests per minute when called. Acts onmock server Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /mocks | Create a mock server from a collection, returning a publicly reachable mock URL. | write | — | Current | |
No per-endpoint scope exists. The created mock server is reachable at the returned mockUrl. Acts onmock server Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MonitorsList monitors, read a single monitor, and run a monitor on demand.3 | ||||||
| GET | /monitors | List monitors the API key can access. | read | — | Current | |
No per-endpoint scope exists. Monitor endpoints are rate-limited to 10 calls per 10 seconds. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 calls / 10 seconds SourceOfficial documentation ↗ | ||||||
| GET | /monitors/{monitorId} | Get a single monitor's configuration and last run details. | read | — | Current | |
No per-endpoint scope exists. Monitor endpoints are rate-limited to 10 calls per 10 seconds. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 calls / 10 seconds SourceOfficial documentation ↗ | ||||||
| POST | /monitors/{monitorId}/run | Run a monitor synchronously and return information about the run. | write | — | Current | |
No per-endpoint scope exists. Running a monitor executes its collection against the live systems it targets. Rate-limited to 10 calls per 10 seconds. Acts onmonitor Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 calls / 10 seconds SourceOfficial documentation ↗ | ||||||
WebhooksCreate a webhook whose URL triggers a collection run.1 | ||||||
| POST | /webhooks | Create a webhook whose URL triggers a collection run through a monitor. | write | — | Current | |
No per-endpoint scope exists. The request body names the collection to run, and the response returns a webhookUrl that, when called, starts the run. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook event collection-run-triggerRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UserRead the authenticated user behind the API key.1 | ||||||
| GET | /me | Get the authenticated user behind the API key, including username, email, and API usage. | read | — | Current | |
No per-endpoint scope exists. Returns the identity and plan usage of whoever created the key. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Postman does not push events to an app or AI agent. Instead, the API can create a webhook that points the other way: a URL Postman gives back that, when called, triggers a collection run through a monitor.
| Event | What it signals | Triggered by |
|---|---|---|
collection run trigger | Not an event Postman pushes. A webhook created through the API returns a URL that, when called by anything that holds it, triggers a run of the named collection through a monitor. | /webhooks |
Postman limits how fast an app or AI agent can call, through an overall per-minute ceiling on each key plus tighter limits on a handful of endpoints and a monthly allowance tied to the plan.
Access to the Postman API with a key is limited to 300 requests per minute. Some endpoints are stricter: Postman Monitors and the GET /collections, GET /workspaces, and GET /workspaces/{id} endpoints are limited to 10 calls in any 10-second window, workspace-update endpoints to 20 requests per minute per user, and the service-account-token endpoint to 10 requests per 10-second window per user. Mock servers, public and private, allow 120 requests per minute. A separate monthly usage allowance applies based on the plan. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, with X-RateLimit-Limit-Month and X-RateLimit-Remaining-Month for the monthly allowance; exceeding a limit returns HTTP 429 with X-RateLimit-RetryAfter and Retry-After giving the seconds to wait.
List endpoints page through results with limit and offset query parameters, returning a slice of the full set per call. Many list endpoints also accept a workspace parameter to scope the results to a single workspace rather than every workspace the key can see.
Requests and responses are JSON. There is no single documented payload size limit across the whole API, though individual resources such as collections and mock servers carry their own plan-based usage limits, like the number of mock-server calls per month.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | The API key is missing, invalid, or expired, so the request was not authenticated. | Send a valid key in the X-API-Key header, regenerating it from Postman account settings if needed. |
| 403 | Forbidden | The key is valid but the user behind it lacks permission for this resource. Because access follows the user's role, a key cannot exceed what its owner can do. | Use a key whose owner has the needed access, or grant that user the permission in Postman. |
| 404 | Not Found | The resource id does not exist, or the key's owner cannot see it. | Confirm the id and that the key's owner has access to the resource. |
| 429 | Too Many Requests | A rate limit was exceeded, either the 300-per-minute overall ceiling, a tighter per-endpoint limit, or the monthly allowance. | Wait the seconds given in the Retry-After and X-RateLimit-RetryAfter headers, then retry. |
The Postman API has no version number in its address. It is published as a single collection that Postman revises over time, and the collection carries a version label, currently v1.39, that marks the cut of endpoints.
The Postman API has no version number in its address; it is published as a public collection that Postman revises, and the collection carries a version label. The v1.39 cut added eight endpoints: six for the API Catalog, covering service monitoring, performance metrics, and compliance data, and two for the Spec Hub, for managing specification version tags and retrieving tagged file snapshots. It was published on 7 May 2026.
Earlier collection versions established the core resource endpoints for collections, environments, workspaces, APIs, mocks, monitors, and the authenticated user. New endpoints are added in later versions without breaking existing calls, so the API has no dated breaking-change timeline of the kind a header-versioned API carries.
New endpoints arrive in later collection versions without breaking the existing ones.
Postman release notes ↗Bollard AI sits between a team's AI agents and Postman. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.