canonical: https://jentic.com/apis/getpostman.com/getpostman

# Getpostman Postman API

The Postman API is the programmatic surface to a Postman workspace, exposing collections, environments, mocks, monitors, APIs, schemas, and webhooks behind a single account-scoped key. It covers 57 endpoints that let teams script collection authoring, version their API definitions, manage mock servers and scheduled monitors, and retrieve schema relations to keep contracts and tests in sync. It is the canonical control plane for orchestrating CI-time API testing, mock-driven development, and API governance across a Postman workspace.

## For AI agents

Manage Postman collections, environments, mocks, monitors, and API schemas across a workspace through an account-scoped X-API-Key.

## Scope

Does not handle source-control hosting, deployment pipelines, or runtime traffic capture - use for managing Postman collections, mocks, monitors, and API schemas only.

## Capabilities

- Create, fetch, update, and fork Postman collections under a workspace
- Manage environment variable sets that drive collection runs
- Spin up and tear down mock servers backed by a collection or schema
- Schedule monitors that run a collection and report results back
- Register an API in Postman, version it, and attach contract test, integration test, and documentation relations
- Upload and update OpenAPI or RAML schemas attached to an API version

## Use cases

### CI-driven contract testing

Engineering teams keep their OpenAPI source of truth in Postman and run contract tests on every pull request. The API lets a CI job upload the latest schema to the API version, link the contract-test collection, and trigger a monitor run, then read results back to gate the merge.

Example prompt: Upload openapi.json to API version v2 of API id abc123 and trigger the linked contract-test monitor

### Mock-first frontend development

Frontend teams build against a Postman mock server while the backend is still landing. The API creates the mock from a collection, returns the mock URL, and lets the team rotate or update the mock as the contract evolves without touching the frontend codebase.

Example prompt: Create a mock named 'payments-mock-staging' bound to collection xyz789 and return the mock URL

### Workspace governance audit

Platform teams audit a workspace by listing every collection, environment, monitor, and registered API to flag stale assets. The API exposes each resource type with stable identifiers, so the audit job can compare current state to a previous snapshot and surface drift such as orphaned mocks or unused environments.

Example prompt: List every collection, environment, and monitor in workspace ws123 and produce a CSV of items not modified in the last 90 days

### AI agent test orchestration

An AI agent connected through Jentic accepts a request like 'run the payments smoke tests against staging', resolves it to a Postman collection plus environment, and triggers a monitor run. Jentic injects the X-API-Key so the agent never holds the workspace credential directly.

Example prompt: Find the collection named 'payments-smoke', bind environment 'staging', and create a one-shot monitor run

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/collections` | List all collections in the workspace |
| POST | `/collections` | Create a new collection |
| POST | `/mocks` | Create a mock server |
| POST | `/monitors` | Schedule a collection monitor |
| POST | `/apis` | Register a new API |
| POST | `/apis/{apiId}/versions/{apiVersionId}/schemas` | Attach a schema to an API version |
| GET | `/environments` | List environments |

## Key resources

- **Collections** — Postman collections containing requests, scripts, and folder structure
- **Environments** — Variable sets that parameterise collection runs across stages
- **Mocks** — Hosted mock servers backed by a collection or schema
- **Monitors** — Scheduled collection runs with result reporting
- **APIs** — Registered APIs with versions and linked schema, doc, and test relations
- **Schemas** — OpenAPI or RAML definitions attached to an API version
- **Webhooks** — Event subscriptions for collection and workspace changes

## Why Jentic

- **Setup:** Wiring Postman by hand means setting its API-key request header and shaping payloads for collections, mocks, monitors, environments, and API schemas across many endpoints yourself. Through Jentic you install once, import the Postman API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Postman exposes collections, mocks, monitors, and environments largely as top-level resources, so you limit the agent to the operations it needs, such as listing collections or creating a monitor. Because you pick the operation set, writes like creating a collection are not reachable unless you add them.
- **Credential handling:** Your Postman API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Postman monitor' or 'list collections', and Jentic returns the matching Postman operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **SwaggerHub API** — API design and governance platform centred on OpenAPI rather than collections
- **WireMock API** — Open-source mocking and stubbing engine that runs locally or self-hosted
- **GitHub API** — Source-control and PR automation that pairs with Postman for contract-test gates

## FAQ

### What authentication does the Postman API use?

Postman uses an account-scoped API key sent as the X-API-Key request header. The same key is also accepted as an apikey query parameter, with the header taking precedence when both are present. Through Jentic the key is vaulted and injected per request.

### Can I create a collection through the Postman API?

Yes. POST /collections accepts a Postman collection JSON document and returns the new collection's identifier. Subsequent updates use PUT `/collections/{collectionId}`, and a fork operation is available via POST `/collections/fork/{collectionId}.`

### What are the rate limits for the Postman API?

The Postman API enforces 60 requests per minute per API key. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; if you exceed the quota you get a 429 response and should back off until the reset epoch.

### How do I run a collection on a schedule through Jentic?

Search Jentic for 'create postman monitor', load the POST /monitors schema, then execute with the collection identifier and an interval. Jentic handles the X-API-Key injection and returns the monitor identifier you can poll later.

### Can I attach an OpenAPI schema to a Postman API version?

Yes. POST `/apis/{apiId}/versions/{apiVersionId}/schemas` uploads a schema document, and PUT on the same path with a schema id replaces it. The sync endpoint at `/apis/{apiId}/versions/{apiVersionId}/{entityType}/{entityId}/syncWithSchema` regenerates linked entities such as collections from the new schema.

### Is the Postman API free?

Access is included with Postman accounts, with usage caps that scale up on paid plans. Heavy automation, large workspaces, and high-frequency monitors typically require a paid tier - check the Postman pricing page for the current per-plan API call allowances.

### Can I limit what my agent is allowed to do with the Postman API?

Yes. Because Jentic One is self-hosted, you decide which Postman operations your agent can reach, and Postman exposes collections, mocks, monitors, and environments as top-level resources you can select individually. You might allow only read operations like listing collections or environments while withholding writes such as creating a collection or scheduling a monitor. Any operation you do not add to the agent's set stays out of reach, and your stored API key is injected at execution time rather than exposed to the agent.