openapi: 3.1.0 info: title: Postman Collections API description: | The Postman Collections API enables you to manage and automate your Postman collections programmatically. Collections are groups of saved API requests that can be organized into folders, include documentation, tests, and pre-request scripts. ## Authentication All requests require an API key passed in the `x-api-key` header. Generate your API key from your Postman account settings. ## Rate Limits The Postman API has rate limits that vary by plan. Free plans are limited to 60 requests per minute. Paid plans have higher limits. ## Base URL All API endpoints are relative to `https://api.getpostman.com`. version: '1.0.0' contact: name: Postman Developer Support url: https://learning.postman.com/docs/developer/postman-api/intro-api/ email: help@postman.com license: name: Postman Terms of Service url: https://www.postman.com/legal/terms/ servers: - url: https://api.getpostman.com description: Postman Production API Server tags: - name: Collections description: Operations for managing Postman collections including CRUD operations, forking, merging, and pull requests. security: - apiKeyAuth: [] paths: /collections: get: tags: - Collections summary: Postman Get all collections operationId: getAllCollections description: >- Gets all of your Postman collections. The response includes all of your subscribed collections. By default, the response returns abbreviated collection data. To get full collection details, use the collection UID. parameters: - name: workspace in: query description: Filter results to a specific workspace by providing the workspace ID. required: false schema: type: string - name: name in: query description: Filter results by collection name (case-insensitive partial match). required: false schema: type: string responses: '200': description: Successful response with list of collections content: application/json: schema: type: object properties: collections: type: array items: $ref: '#/components/schemas/CollectionListItem' '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' post: tags: - Collections summary: Postman Create a collection operationId: createCollection description: >- Creates a new collection in your Postman account. You can include the collection content in the request body, including requests, folders, and scripts. parameters: - name: workspace in: query description: The workspace ID to create the collection in. If not specified, the collection is created in your personal workspace. required: false schema: type: string requestBody: required: true content: application/json: schema: type: object required: - collection properties: collection: $ref: '#/components/schemas/CollectionInput' responses: '200': description: Successfully created collection content: application/json: schema: type: object properties: collection: type: object properties: id: type: string description: The collection's unique ID name: type: string description: The collection name uid: type: string description: The collection's unique identifier in the format {ownerId}-{collectionId} '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' /collections/{collectionId}: get: tags: - Collections summary: Postman Get a collection operationId: getCollection description: >- Gets information about a single collection. The response includes the full collection definition including requests, folders, scripts, variables, and other metadata. parameters: - $ref: '#/components/parameters/CollectionIdParam' - name: access_key in: query description: A collection's read-only access key. Using this parameter does not require an API key. required: false schema: type: string responses: '200': description: Successful response with collection details content: application/json: schema: type: object properties: collection: $ref: '#/components/schemas/Collection' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' put: tags: - Collections summary: Postman Update a collection operationId: updateCollection description: >- Updates an existing collection. This replaces the entire collection definition with the data provided in the request body. Acts as a complete replacement, not a partial update. parameters: - $ref: '#/components/parameters/CollectionIdParam' requestBody: required: true content: application/json: schema: type: object required: - collection properties: collection: $ref: '#/components/schemas/CollectionInput' responses: '200': description: Successfully updated collection content: application/json: schema: type: object properties: collection: type: object properties: id: type: string name: type: string uid: type: string '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' delete: tags: - Collections summary: Postman Delete a collection operationId: deleteCollection description: >- Deletes a collection from your Postman account. This action is irreversible. parameters: - $ref: '#/components/parameters/CollectionIdParam' responses: '200': description: Successfully deleted collection content: application/json: schema: type: object properties: collection: type: object properties: id: type: string uid: type: string '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' /collections/{collectionId}/requests: get: tags: - Collections summary: Postman Get all requests in a collection operationId: getCollectionRequests description: >- Gets all the requests in a collection. Returns request metadata including name, method, URL, and folder hierarchy. parameters: - $ref: '#/components/parameters/CollectionIdParam' responses: '200': description: Successful response with list of requests content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RequestListItem' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' /collections/{collectionId}/folders: get: tags: - Collections summary: Postman Get all folders in a collection operationId: getCollectionFolders description: >- Gets all the folders in a collection. Returns folder metadata and hierarchy structure. parameters: - $ref: '#/components/parameters/CollectionIdParam' responses: '200': description: Successful response with list of folders content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/FolderListItem' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' /collections/{collectionId}/responses: get: tags: - Collections summary: Postman Get all responses in a collection operationId: getCollectionResponses description: >- Gets all saved example responses in a collection. Includes response body, headers, and status codes. parameters: - $ref: '#/components/parameters/CollectionIdParam' responses: '200': description: Successful response with list of responses content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ResponseListItem' meta: $ref: '#/components/schemas/PaginationMeta' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' /collections/fork/{collectionId}: post: tags: - Collections summary: Postman Fork a collection operationId: forkCollection description: >- Creates a fork of an existing collection into a specified workspace. Forking creates a copy that maintains a link to the source collection for future merges. parameters: - $ref: '#/components/parameters/CollectionIdParam' - name: workspace in: query description: The workspace ID to fork the collection into. required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - label properties: label: type: string description: The fork label responses: '200': description: Successfully forked collection content: application/json: schema: type: object properties: collection: type: object properties: id: type: string name: type: string uid: type: string fork: type: object properties: label: type: string from: type: string '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' /collections/merge: post: tags: - Collections summary: Postman Merge a fork operationId: mergeCollection description: >- Merges a forked collection back into its source collection. You can choose the merge strategy to resolve conflicts. requestBody: required: true content: application/json: schema: type: object required: - source - destination properties: strategy: type: string enum: - deleteSource - updateSourceWithDestination description: The merge strategy to use source: type: string description: The source collection UID (the fork) destination: type: string description: The destination collection UID (the original) responses: '200': description: Successfully merged collection content: application/json: schema: type: object properties: collection: type: object properties: id: type: string uid: type: string '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '429': $ref: '#/components/responses/RateLimitError' components: securitySchemes: apiKeyAuth: type: apiKey name: x-api-key in: header description: Postman API key for authentication. Generate from your Postman account settings. parameters: CollectionIdParam: name: collectionId in: path required: true description: The collection's unique ID or UID. schema: type: string schemas: CollectionListItem: type: object description: Abbreviated collection information returned in list responses. properties: id: type: string description: The collection's unique ID name: type: string description: The collection name owner: type: string description: The owner ID of the collection uid: type: string description: The collection's UID in the format {ownerId}-{collectionId} createdAt: type: string format: date-time description: The date and time at which the collection was created updatedAt: type: string format: date-time description: The date and time at which the collection was last updated isPublic: type: boolean description: Whether the collection is publicly accessible fork: type: object description: Fork information if the collection is a fork properties: label: type: string createdAt: type: string format: date-time from: type: string Collection: type: object description: Full collection definition including requests, folders, and metadata. properties: info: type: object properties: name: type: string description: The collection name description: type: string description: The collection description in Markdown format schema: type: string description: The collection schema URL _postman_id: type: string description: The collection's Postman ID updatedAt: type: string format: date-time item: type: array description: The collection's items (requests and folders) items: $ref: '#/components/schemas/CollectionItem' variable: type: array description: Collection-level variables items: $ref: '#/components/schemas/Variable' auth: $ref: '#/components/schemas/Auth' event: type: array description: Collection-level scripts (pre-request and test scripts) items: $ref: '#/components/schemas/Event' CollectionInput: type: object description: Input format for creating or updating a collection. required: - info properties: info: type: object required: - name - schema properties: name: type: string description: The collection name description: type: string description: The collection description schema: type: string description: The Postman collection schema URL example: https://schema.getpostman.com/json/collection/v2.1.0/collection.json item: type: array items: $ref: '#/components/schemas/CollectionItem' variable: type: array items: $ref: '#/components/schemas/Variable' auth: $ref: '#/components/schemas/Auth' event: type: array items: $ref: '#/components/schemas/Event' CollectionItem: type: object description: A request or folder within a collection. properties: name: type: string description: The item name id: type: string description: The item ID request: type: object description: The request definition (present for request items) properties: method: type: string enum: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS] url: oneOf: - type: string - type: object properties: raw: type: string host: type: array items: type: string path: type: array items: type: string query: type: array items: type: object properties: key: type: string value: type: string header: type: array items: type: object properties: key: type: string value: type: string body: type: object properties: mode: type: string enum: [raw, urlencoded, formdata, file, graphql] raw: type: string description: type: string response: type: array description: Saved example responses items: type: object item: type: array description: Sub-items (for folder items) items: $ref: '#/components/schemas/CollectionItem' event: type: array items: $ref: '#/components/schemas/Event' RequestListItem: type: object properties: id: type: string name: type: string method: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time FolderListItem: type: object properties: id: type: string name: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time ResponseListItem: type: object properties: id: type: string name: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time Variable: type: object description: A Postman variable with key-value pair and type. properties: key: type: string value: type: string type: type: string enum: [string, boolean, number, any] description: type: string Auth: type: object description: Authentication configuration for requests. properties: type: type: string enum: [apikey, awsv4, basic, bearer, digest, edgegrid, hawk, noauth, ntlm, oauth1, oauth2] description: The authentication type Event: type: object description: A script event (pre-request or test). properties: listen: type: string enum: [prerequest, test] description: When the script runs script: type: object properties: type: type: string example: text/javascript exec: type: array items: type: string PaginationMeta: type: object properties: total: type: integer description: Total count of items limit: type: integer description: Maximum number of items per page offset: type: integer description: Current offset responses: BadRequestError: description: Bad request - invalid input or malformed request body content: application/json: schema: type: object properties: error: type: object properties: name: type: string example: badRequestError message: type: string UnauthorizedError: description: Authentication credentials are missing or invalid content: application/json: schema: type: object properties: error: type: object properties: name: type: string example: authenticationError message: type: string example: Invalid API Key. Every request requires a valid API Key to be sent. NotFoundError: description: The requested resource was not found content: application/json: schema: type: object properties: error: type: object properties: name: type: string example: instanceNotFoundError message: type: string RateLimitError: description: Too many requests - rate limit exceeded content: application/json: schema: type: object properties: error: type: string example: rateLimited message: type: string example: Rate limit exceeded. Please retry after some time. InternalServerError: description: An unexpected error occurred on the server content: application/json: schema: type: object properties: error: type: object properties: name: type: string example: serverError message: type: string