Postman Collections API
The Collections API lets you programmatically create, read, update, and delete Postman Collections including requests, folders, scripts, and environments. Powers CI/CD integration, sync, and collection generation pipelines.
OpenAPI Specification
openapi: 3.1.0
info:
title: Postman APIs API Comments Collections API
description: 'The Postman APIs API enables you to manage your API definitions in Postman''s
API Builder. You can create APIs, manage versions, add schemas (OpenAPI,
GraphQL, etc.), and link collections, environments, mock servers, monitors,
and documentation to your API definitions.
## Authentication
All requests require an API key passed in the `x-api-key` header.
## Rate Limits
Standard Postman API rate limits apply.
'
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
security:
- apiKeyAuth: []
tags:
- name: Collections
description: Operations for managing Postman collections including CRUD operations, forking, merging, and pull requests.
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:
schemas:
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
FolderListItem:
type: object
properties:
id:
type: string
name:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
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
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
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'
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'
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
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'
ResponseListItem:
type: object
properties:
id:
type: string
name:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
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
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
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
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
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.
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
parameters:
CollectionIdParam:
name: collectionId
in: path
required: true
description: The collection's unique ID or UID.
schema:
type: string
securitySchemes:
apiKeyAuth:
type: apiKey
name: x-api-key
in: header
description: Postman API key for authentication.