Postman api API
The api API from Postman — 16 operation(s) for api.
The api API from Postman — 16 operation(s) for api.
openapi: 3.1.0
info:
title: Postman API
version: 1.0.0
description: 'Operations tagged api across 2 of this provider''s published API definitions: postman-api-api-openapi.yml, postman-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: api
paths:
/apis:
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
get:
operationId: getApis
summary: Get all APIs
description: Gets information about all APIs in a workspace.
tags:
- api
parameters:
- name: workspaceId
in: query
description: The workspace's ID.
required: true
schema:
$ref: '#/components/schemas/workspaceId'
- name: createdBy
in: query
description: Return only results created by the given user ID.
required: false
schema:
$ref: '#/components/schemas/createdBy'
- 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: description
in: query
description: Return only APIs whose description includes the given value. Matching is not case-sensitive.
required: false
schema:
$ref: '#/components/schemas/apiDescription'
- 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: x-api-key
in: header
required: true
schema:
type: string
- name: Accept
in: header
description: The `application/vnd.api.v10+json` request header required to use the endpoint.
required: true
schema:
$ref: '#/components/schemas/v10Accept'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getApis'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetApisRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/GetApisRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/GetApisRequestNotFoundError'
'422':
description: v9 Unsupported
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetApisRequestInternalServerError'
post:
operationId: createApi
summary: Create an API
description: Creates an API.
tags:
- api
parameters:
- name: workspaceId
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
- name: Accept
in: header
description: The `application/vnd.api.v10+json` request header required to use the endpoint.
required: true
schema:
$ref: '#/components/schemas/v10Accept'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createApiResponse'
'400':
description: Missing Workspace ID
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createUpdateApi'
/apis/{apiId}:
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
get:
operationId: getApi
summary: Get an API
description: 'Gets information about an API.
**Note:**
- Git-connected APIs will only return the `versions` and `gitInfo` query responses. This is because schema and collection information is stored in the connected Git repository. The `gitInfo` object only lists the repository and folder locations of the files.
- API viewers can only use the `versions` option in the `include` query parameter.
'
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: include
in: query
description: 'An array that contains additional resources to include in the response. Use this parameter to query for element links to the API, such as collections and schemas:
- `collections` — Query for linked Postman collections.
- `versions` — Query for linked versions.
- `schemas` — Query for linked schemas.
- `gitInfo` — Query for information about the API''s git-linked repository. This query only returns the linked repository and folder locations of the files. It does not return `collections` or `schemas` information.
**Note:**
API viewers can only use the `versions` option.
'
required: false
schema:
$ref: '#/components/schemas/apiInclude'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: Accept
in: header
description: The `application/vnd.api.v10+json` request header required to use the endpoint.
required: true
schema:
$ref: '#/components/schemas/v10Accept'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getApi'
'400':
description: Missing v10 Accept Header
content:
application/json:
schema:
$ref: '#/components/schemas/apiErrorNameMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/GetApiRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/GetApiRequestNotFoundError'
'422':
description: v9 Unsupported
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetApiRequestInternalServerError'
put:
operationId: updateApi
summary: Update an API
description: Updates an API.
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: Accept
in: header
description: The `application/vnd.api.v10+json` request header required to use the endpoint.
required: true
schema:
$ref: '#/components/schemas/v10Accept'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/updateApiResponse'
'400':
description: Missing v10 Accept Header
content:
application/json:
schema:
$ref: '#/components/schemas/apiErrorNameMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateApiRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateApiRequestNotFoundError'
'422':
description: v9 Unsupported
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateApiRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createUpdateApi'
delete:
operationId: deleteApi
summary: Delete an API
description: Deletes an API. On success, this returns an HTTP `204 No Content` response.
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: Accept
in: header
description: The `application/vnd.api.v10+json` request header required to use the endpoint.
required: true
schema:
$ref: '#/components/schemas/v10Accept'
responses:
'204':
description: No Content
content:
application/json:
schema:
type: object
properties: {}
'400':
description: Missing v10 Accept Header
content:
application/json:
schema:
$ref: '#/components/schemas/apiErrorNameMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteApiRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteApiRequestNotFoundError'
'422':
description: v9 Unsupported
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteApiRequestInternalServerError'
/apis/{apiId}/collections:
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
post:
operationId: addApiCollection
summary: Add a collection
description: "Adds a collection to an API. To do this, use the following `operationType` values:\n\n- `COPY_COLLECTION` — Copies a collection from the workspace and adds it to an API.\n- `CREATE_NEW` — Creates a new collection by providing the new collection's content.\n- `GENERATE_FROM_SCHEMA` — Generates the collection from an API schema.\n - `options` — An object that contains advanced creation options and their values. You can find a complete list of properties and their values in Postman's [OpenAPI to Postman Collection Converter OPTIONS documentation](https://github.com/postmanlabs/openapi-to-postman/blob/develop/OPTIONS.md). These properties are case-sensitive.\n"
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: Accept
in: header
description: The `application/vnd.api.v10+json` request header required to use the endpoint.
required: true
schema:
$ref: '#/components/schemas/v10Accept'
responses:
'200':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/addApiCollectionResponse'
'400':
description: Missing v10 Accept Header
content:
application/json:
schema:
$ref: '#/components/schemas/apiErrorNameMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/AddApiCollectionRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/AddApiCollectionRequestNotFoundError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/AddApiCollectionRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/API_addApiCollection_Request'
/apis/{apiId}/collections/{collectionId}:
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
get:
operationId: getApiCollection
summary: Get a collection
description: 'Gets a collection attached to an API. You can use the `versionId` query parameter to get a collection published in a version.
**Note:**
- You cannot use this endpoint to get a Git-linked API collection. Collections in a Git-linked API are stored in the linked Git repository, not in the Postman cloud. This endpoint only has access to Postman servers.
- You can get a collection published in an API version with the `versionId` query parameter.
- The `versionId` query parameter is a required parameter for API viewers.
'
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionIdApi'
- name: versionId
in: query
description: The API's version ID. This is a required parameter for API viewers.
required: false
schema:
$ref: '#/components/schemas/apiVersionId'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: Accept
in: header
description: The `application/vnd.api.v10+json` request header required to use the endpoint.
required: true
schema:
$ref: '#/components/schemas/v10Accept'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getApiCollection'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/GetApiCollectionRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/GetApiCollectionRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/GetApiCollectionRequestNotFoundError'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetApiCollectionRequestInternalServerError'
/apis/{apiId}/collections/{collectionId}/comments:
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
get:
operationId: getApiCollectionComments
summary: Get a collection's comments
description: Gets all comments left by users in an API's collection.
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionIdApi'
- 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: createApiCollectionComment
summary: Create a collection comment
description: 'Creates a comment on an API''s 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:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionIdApi'
- 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'
/apis/{apiId}/collections/{collectionId}/comments/{commentId}:
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
put:
operationId: updateApiCollectionComment
summary: Update a collection's comment
description: 'Updates a comment on an API''s collection.
**Note:**
This endpoint accepts a max of 10,000 characters.
'
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionIdApi'
- 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: deleteApiCollectionComment
summary: Delete a collection's comment
description: 'Deletes a comment from an API''s 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:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionIdApi'
- 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'
/apis/{apiId}/collections/{collectionId}/sync-with-schema-tasks:
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
put:
operationId: syncCollectionWithSchema
summary: Sync collection with schema
description: 'Syncs a collection attached to an API with the API schema.
This is an asynchronous endpoint that returns an HTTP `202 Accepted` response. The response contains a polling link to the `/apis/{apiId}/tasks/{taskId}` endpoint in the `Location` header.
**Note:**
This endpoint only supports the OpenAPI 3 schema type.
'
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: collectionId
in: path
description: The collection's unique ID.
required: true
schema:
$ref: '#/components/schemas/collectionIdApi'
- name: x-api-key
in: header
required: true
schema:
type: string
- name: Accept
in: header
description: The `application/vnd.api.v10+json` request header required to use the endpoint.
required: true
schema:
$ref: '#/components/schemas/v10Accept'
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/syncCollectionWithSchemaResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/SyncCollectionWithSchemaRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetailStatusInstance'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/SyncCollectionWithSchemaRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/SyncCollectionWithSchemaRequestNotFoundError'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorTypeTitleDetail'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/SyncCollectionWithSchemaRequestInternalServerError'
/apis/{apiId}/comments:
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
get:
operationId: getApiComments
summary: Get an API's comments
description: Gets all comments left by users in an API.
tags:
- api
parameters:
- name: apiId
in: path
description: The API's ID.
required: true
schema:
$ref: '#/components/schemas/apiId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/commentResponse'
'400':
description: Missing v10 Accept Header
content:
application/json:
schema:
$ref: '#/components/schemas/apiErrorNameMessage'
'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: createApiComment
summary: Create an API comment
description: 'Creates a comment on an API. 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:
- api
parameters:
- name: apiId
in: path
description
# --- truncated at 32 KB (140 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/postman/refs/heads/main/openapi/postman-api-api-openapi.yml