Postman Collections API
Use the Collections APIs to manage your Postman collections and simplify collection-related workflows, with endpoints to add, delete, or update your collections.
OpenAPI Specification
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: [email protected]
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