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.
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: 3.1.0
info:
title: Postman Collections API
version: 1.0.0
description: 'Operations tagged collections across 2 of this provider''s published API definitions: postman-api-openapi.yml, postman-collections-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
tags:
- name: collections
paths:
/collection-merges:
put:
operationId: asyncMergePullCollectionFork
summary: Merge or pull changes into a collection fork
description: '[Merges](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements/#merge-changes-from-a-fork) a forked (source) collection and its parent (destination) collection asynchronously. To pull changes into a fork, pass the forked collection''s ID as the `destination` value and the parent collection ID as the `source` value.
The response returns a task `id` value, which you can use to track the merge''s status with the GET `/collection-merges-tasks/{taskId}` endpoint.
'
tags:
- collections
parameters:
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/asyncMergeCollectionFork'
'400':
description: Malformed Request
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncMergePullCollectionForkRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncMergePullCollectionForkRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/asyncCollectionForkMerge'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collection-merges-tasks/{taskId}:
get:
operationId: asyncMergePullCollectionTaskStatus
summary: Get merge or pull task status
description: 'Gets the status of a collection''s merge or a pull changes task.
**Note:**
After a merge''s success or failure, the task''s status is only available for a period of 24 hours. Afterwards, this endpoint returns an HTTP `404 Not Found` response.
'
tags:
- collections
parameters:
- name: taskId
in: path
description: The task's ID.
required: true
schema:
$ref: '#/components/schemas/collectionForkTaskId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Task Status Response
content:
application/json:
schema:
$ref: '#/components/schemas/asyncMergePullCollectionTaskStatus'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncMergePullCollectionTaskStatusRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'404':
description: Task Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncMergePullCollectionTaskStatusRequestInternalServerError'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collections:
get:
operationId: getCollections
summary: Get all collections
description: 'Gets all of your [collections](https://www.postman.com/docs/collections). The response includes all of your subscribed collections.
**Note:**
- It''s recommended that you use pagination with this endpoint. Pagination improves endpoint performance. Unpaginated calls are considered deprecated and are subject to change.
- Filtering with the `name` parameter when you also pass the `limit` and `offset` parameters is not supported.
- If you pass an invalid workspace ID for the `workspace` query parameter, this endpoint returns an HTTP `200 OK` response with an empty array.
'
tags:
- collections
parameters:
- name: workspace
in: query
description: The workspace's ID.
required: false
schema:
$ref: '#/components/schemas/workspaceId'
- name: name
in: query
description: Filter results by collections whose name exactly matches the given value. Partial or substring matches are not supported.
required: false
schema:
$ref: '#/components/schemas/collectionNameQuery'
- name: limit
in: query
description: The maximum number of rows to return in the response.
required: false
schema:
$ref: '#/components/schemas/limitNoDefault'
- name: offset
in: query
description: The zero-based offset of the first item to return.
required: false
schema:
$ref: '#/components/schemas/offsetNoDefault'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getCollections'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetCollectionsRequestUnauthorizedError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetCollectionsRequestInternalServerError'
post:
operationId: createCollection
summary: Create a collection
description: 'Creates a collection using the [Postman Collection v2.1.0 schema format](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).
**Note:**
If you do not include the `workspace` query parameter, the system creates the collection in the oldest personal Internal workspace you own.
'
tags:
- collections
parameters:
- name: workspace
in: query
description: The workspace's ID.
required: true
schema:
$ref: '#/components/schemas/workspaceId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/collectionCreated'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessageDetails'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollectionRequestUnauthorizedError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollectionRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createCollection'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collections/collection-forks:
get:
operationId: getCollectionsForkedByUser
summary: Get all forked collections
description: Gets a list of all the authenticated user's forked collections.
tags:
- collections
parameters:
- name: cursor
in: query
description: The pointer to the first record of the set of paginated results. To view the next response, use the `nextCursor` value for this parameter.
required: false
schema:
$ref: '#/components/schemas/cursor'
- name: limit
in: query
description: The maximum number of rows to return in the response.
required: false
schema:
$ref: '#/components/schemas/limit'
default: 10
- name: direction
in: query
description: Sort the results by creation date in ascending (`asc`) or descending (`desc`) order.
required: false
schema:
$ref: '#/components/schemas/ascDesc'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getCollectionsForkedByUser'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/fork400ErrorNoUserFound'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetCollectionsForkedByUserRequestUnauthorizedError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetCollectionsForkedByUserRequestInternalServerError'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collections/fork/{collectionId}:
post:
operationId: createCollectionFork
summary: Create a fork
description: Creates a [fork](https://learning.postman.com/docs/collaborating-in-postman/version-control/#creating-a-fork) from an existing collection into a workspace.
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's ID.
required: true
schema:
$ref: '#/components/schemas/collectionId'
- name: workspace
in: query
description: The workspace ID in which to create the fork.
required: true
schema:
$ref: '#/components/schemas/workspaceId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createCollectionForkResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollectionForkRequestUnauthorizedError'
'404':
description: Instance Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessageDetails'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCollectionForkRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createCollectionFork'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collections/merge:
post:
operationId: mergeCollectionFork
summary: Merge a fork
description: '**This endpoint is deprecated.**
Merges a forked collection back into its parent collection. You must have the [Editor role](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#collection-roles) for the collection to merge a fork.
'
tags:
- collections
parameters:
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/mergeCollectionForkResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/MergeCollectionForkRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/MergeCollectionForkRequestForbiddenError'
'404':
description: Instance Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessageDetails'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/MergeCollectionForkRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/mergeCollectionFork'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collections/{collectionId}:
get:
operationId: getCollection
summary: Get a collection
description: Gets information about a collection. For a complete list of this endpoint's possible values, refer to the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's ID.
required: true
schema:
$ref: '#/components/schemas/collectionId'
- name: access_key
in: query
description: A collection's read-only access key. Using this query parameter does not require an API key to call the endpoint.
required: false
schema:
$ref: '#/components/schemas/collectionAccessKeyQuery'
- name: model
in: query
description: Return a list of only the collection's root-level request (`rootLevelRequests`) and folder (`rootLevelFolders`) IDs instead of the full collection element data.
required: false
schema:
$ref: '#/components/schemas/collectionModelQuery'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getCollection'
'400':
description: Collection Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetCollectionRequestUnauthorizedError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetCollectionRequestInternalServerError'
put:
operationId: putCollection
summary: Replace a collection's data
description: 'Replaces the contents of a collection using the [Postman Collection v2.1.0 schema format](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html). Include the collection''s ID values in the request body. If you do not, the endpoint removes the existing items and creates new items.
- To perform an update asynchronously, use the `Prefer` header with the `respond-async` value. When performing an async update, this endpoint returns a HTTP `202 Accepted` response.
- For a complete list of properties and information, see the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).
- For protocol profile behavior, refer to Postman''s [Protocol Profile Behavior documentation](https://github.com/postmanlabs/postman-runtime/blob/develop/docs/protocol-profile-behavior.md).
**Note:**
- The maximum collection size this endpoint accepts cannot exceed 100 MB.
- Use the GET `/collection-updates-tasks/{taskId}` endpoint to get the collection''s update status when performing an asynchronous update.
- If you don''t include the collection items'' ID values from the request body, the endpoint **removes** the existing items and recreates the items with new ID values.
- To copy another collection''s contents to the given collection, remove all ID values before you pass it in this endpoint. If you do not, this endpoint returns an error. These values include the `id`, `uid`, and `postman_id` values.
'
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's ID.
required: true
schema:
$ref: '#/components/schemas/collectionId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: Prefer
in: header
description: The `respond-async` header to perform the update asynchronously.
required: false
schema:
$ref: '#/components/schemas/Prefer'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/putCollectionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/PutCollectionRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PutCollectionRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/PutCollectionRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/PutCollectionRequestNotFoundError'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PutCollectionRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/putCollection'
delete:
operationId: deleteCollection
summary: Delete a collection
description: Deletes a collection.
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's ID.
required: true
schema:
$ref: '#/components/schemas/collectionId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/deleteCollection'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCollectionRequestUnauthorizedError'
'404':
description: Instance Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessageDetails'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteCollectionRequestInternalServerError'
patch:
operationId: patchCollection
summary: Update part of a collection
description: 'Updates specific collection information, such as its name, events, or its variables. For more information, see the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).
'
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's ID.
required: true
schema:
$ref: '#/components/schemas/collectionId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/patchCollectionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/PatchCollectionRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/PatchCollectionRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/PatchCollectionRequestForbiddenError'
'404':
description: Instance Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessageDetails'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/PatchCollectionRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/patchCollection'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collections/{collectionId}/comments:
get:
operationId: getCollectionComments
summary: Get a collection's comments
description: Gets all comments left by users in a collection.
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionUid'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/commentResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
post:
operationId: createCollectionComment
summary: Create a collection comment
description: 'Creates a comment on a collection. To create a reply on an existing comment, include the `threadId` property in the request body.
**Note:**
This endpoint accepts a max of 10,000 characters.
'
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionUid'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/commentCreatedUpdated'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/commentCreate'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collections/{collectionId}/comments/{commentId}:
put:
operationId: updateCollectionComment
summary: Update a collection's comment
description: 'Updates a comment on a collection.
**Note:**
This endpoint accepts a max of 10,000 characters.
'
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionUid'
- name: commentId
in: path
description: The comment's ID.
required: true
schema:
$ref: '#/components/schemas/commentId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/commentCreatedUpdated'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/commentUpdate'
delete:
operationId: deleteCollectionComment
summary: Delete a collection's comment
description: 'Deletes a comment from a collection. On success, this returns an HTTP `204 No Content` response.
**Note:**
Deleting the first comment of a thread deletes all the comments in the thread.
'
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionUid'
- name: commentId
in: path
description: The comment's ID.
required: true
schema:
$ref: '#/components/schemas/commentId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'204':
description: No Content
content:
application/json:
schema:
type: object
properties: {}
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/collections/{collectionId}/duplicates:
post:
operationId: duplicateCollection
summary: Duplicate a collection
description: 'Creates a duplicate of the given collection in another workspace.
Use the GET `/collection-duplicate-tasks/{taskId}` endpoint to get the duplication task''s current status.
'
tags:
- collections
parameters:
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionUid'
- name: x-api-key
in: header
required: true
schema:
# --- truncated at 32 KB (171 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/postman/refs/heads/main/openapi/postman-collections-api-openapi.yml