Postman API

openapi: 3.0.3
info:
  title: Postman API
  description: |
    The Postman API enables you to programmatically access data stored in your Postman account.

    > Certain endpoints may be unavailable depending on your region and/or Postman plan.

    For a comprehensive set of examples of requests and responses, see the [**Postman API** collection](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a).

    ## Getting started

    You can get started with the Postman API by creating a copy of this definition in your workspace.

    ### EU users

    For users in the EU with [**Enterprise** plans](https://www.postman.com/pricing/), the Postman API uses the `http://api.eu.postman.com` subdomain. This is available in the definition's list of servers. You can change this by selecting the `http://api.eu.postman.com` subdomain in the **Server** dropdown list below.

    ## About the Postman API

    - You must use a valid API Key to send requests to the API endpoints.
    - The API has [rate and usage limits](https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/).
    - The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP `301` redirect to the corresponding HTTPS resources.
    - The API returns requests responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key.
    - The request method (verb) determines the nature of action you intend to perform. A request made using the `GET` method implies that you want to fetch something from Postman. The `POST` method implies you want to save something new to Postman.
    - For all requests, API calls respond with their corresponding [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). In the Postman client, the status code also provides help text that details the possible meaning of the response code.
    - When calling the API Builder endpoints, you must send an `Accept` header with the `application/vnd.api.v10+json` value.

    ### IDs and UIDs

    All items in Postman, such as collections, workspaces, and APIs, have IDs and UIDs:

    - An ID is the unique ID assigned to a Postman item. For example, `ec29121c-5203-409f-9e84-e83ffc10f226`.
    - The UID is the **full** ID of a Postman item. This value is the item's unique ID concatenated with the user ID. For example, in the `12345678-ec29121c-5203-409f-9e84-e83ffc10f226` UID:
        - `12345678` is the user's ID.
        - `ec29121c-5203-409f-9e84-e83ffc10f226` is the item's ID.

    ### Enum values

    Any documented enum values should be considered partial lists and may change over time.

    ### 403 response for unavailable features

    Depending on your region and/or Postman [plan](https://www.postman.com/pricing/), some endpoints will return an HTTP `403 Forbidden` response with the "This feature isn't available in your region." detail.

    ### 503 response

    An HTTP `503 Service Unavailable` response from our servers indicates there is an unexpected spike in API access traffic. The server is usually operational within the next five minutes.

    If the outage persists or you receive any other form of an HTTP `5XX` error, [contact support](https://support.postman.com/hc/en-us/requests/new/).

    ## Authentication

    Postman uses API keys for authentication. The API key tells the API server that the request came from you. Everything that you have access to in Postman is accessible with your API key. You can [generate](https://learning.postman.com/docs/developer/postman-api/authentication/#generate-a-postman-api-key) a Postman API key in the [**API keys**](https://postman.postman.co/settings/me/api-keys) section of your Postman account settings.

    You must include an API key in each request to the Postman API with the `X-API-Key` request header. In Postman, you can store your API key as a [vault secret](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/) or an [environment variable](https://www.getpostman.com/docs/environments). The Postman API [collection](https://www.getpostman.com/docs/collections) will use it to make API calls.

    ### SCIM authentication

    While all other endpoints in this collection require a Postman API key, the SCIM endpoints require a [SCIM API key](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/#generating-scim-api-key).

    ### Authentication error response

    If an API key is missing, malformed, or invalid, you will receive an HTTP `401 Unauthorized` response code.

    ## Rate and usage limits

    API access [rate limits](https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/) apply at a per-user basis in unit time. The limit is **300 requests per minute**. Postman Monitors, the GET `/collections`, and the GET `/workspaces` endpoint have a rate limit of **10 calls in 10 seconds**. Depending on your [plan](https://www.postman.com/pricing/), you may also have [usage limits](https://learning.postman.com/docs/billing/resource-usage/).

    When you reach your rate or usage limits, the API returns the following HTTP `429 Too Many Requests` status code with one of the following error responses:

    - `rateLimited` — Rate limits reached. The response returns the time after which you can resume calls to the Postman API.
    - `serviceLimitExhausted` — Postman API service limits reached. You will need to contact your Postman Team Admin for assistance.

    ## Support

    For help regarding accessing the Postman API, you can:

    - Visit [Postman Support](https://support.postman.com/hc/en-us) or our [Community and Support](https://www.postman.com/community/) sites.
    - Reach out to the [Postman community](https://community.postman.com/).
    - Submit a help request to [Postman support](https://support.postman.com/hc/en-us/requests/new/).

    ## Policies

    - [Postman Terms of Service](http://www.postman.com/legal/terms/)
    - [Postman Privacy Policy](https://www.postman.com/legal/privacy-policy/)
  version: '1.0'
  termsOfService: https://www.postman.com/legal/terms/
  contact:
    name: Postman Support
    email: help@postman.com
    url: https://www.postman.com/community/
servers:
  - url: https://api.getpostman.com
  - url: https://api.eu.postman.com
security:
  - PostmanApiKey: []
  - scimApiKey: []
tags:
  - name: API Security
    description: The **API Security** endpoints enable you to manage the [security of your API](https://learning.postman.com/docs/api-governance/api-definition/api-definition-warnings/). API security includes ensuring you follow security and format warnings and schema validation.
  - name: API Tags
    description: The **API Tags** endpoints enable you to manage API tags with Postman's [tagging](https://learning.postman.com/docs/designing-and-developing-your-api/managing-apis/#tagging-apis) feature. Tagging is available on Postman [**Enterprise** plans](https://www.postman.com/pricing/).
  - name: API Versions
    description: The **API Versions** endpoints enable you to manage your [API's versions](https://learning.postman.com/docs/designing-and-developing-your-api/versioning-an-api/versioning-an-api-overview/#publishing-an-api-version). Only users with the [API Admin](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#api-roles) or [Workspace Admin](https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#workspace-roles) role can publish and manage versions.
  - name: Audit Logs
    description: The [**Audit Logs**](https://learning.postman.com/docs/administration/audit-logs/) endpoints enable you to monitor and analyze your Professional or Enterprise Postman teams. These endpoints are only available on Postman [**Professional** and **Enterprise** plans](https://www.postman.com/pricing).
  - name: Billing
    description: The **Billing** endpoints enable you to manage your Postman billing account, such as your team's plan and [billing](https://learning.postman.com/docs/billing/billing/) information.
  - name: Collection Access Keys
    description: |
      The **Collection Access Keys** endpoints enable you to manage your [collection access keys](https://learning.postman.com/docs/developer/postman-api/authentication/#generate-a-collection-access-key). Collection access keys enable you to securely grant other users read-only access to a collection.

      Collection access keys are valid for 60 days. If unused, the access key expires after 60 days. If someone uses the access key, then its expiration date increases by another 60 days.
  - name: Collection Folders
    description: The **Collection Folders** endpoints enable you to manage collection folders.
  - name: Collection Items
    description: The **Collection Items** endpoints enable you to manage a collection's items, such as folders and requests.
  - name: Collection Requests
    description: The **Collection Requests** endpoints enable you to manage collection requests.
  - name: Collection Responses
    description: The **Collection Responses** endpoints enable you to manage collection responses.
  - name: Collection Tags
    description: The **Collection Tags** endpoints enable you to manage collection tags with Postman's [tagging](https://learning.postman.com/docs/collections/using-collections/#tagging-a-collection) feature. Tagging is available on Postman [**Enterprise** plans](https://www.postman.com/pricing/).
  - name: Collection to API
    description: The **Collection to API** endpoints enable you to transform your Postman Collections into API definitions.
  - name: Collections
    description: The **Collections** endpoints enable you to manage your Postman [Collections](https://learning.postman.com/docs/sending-requests/intro-to-collections/).
  - name: Comments
    description: The **Comments** endpoints enable you to manage comments on an API element. You can use [comments](https://learning.postman.com/docs/collaborating-in-postman/working-with-your-team/discussing-your-work/) to collaborate and discuss your work with your teammates in Postman.
  - name: Detected Secrets
    description: The **Detected Secrets** endpoints enable you to manage secrets detected by the Postman [Secret Scanner](https://learning.postman.com/docs/administration/secret-scanner/).
  - name: Environments
    description: The **Environments** endpoints enable you to manage your Postman [environments](https://learning.postman.com/docs/sending-requests/managing-environments/).
  - name: Forks
    description: The **Forks** endpoints enable you to manage element [forks](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/forking-elements/). Forks are new instances of an element that you can change without making any changes to the parent element.
  - name: Global Variables
    description: The **Global Variables** endpoints enable you to manage global [variables](https://learning.postman.com/docs/sending-requests/variables/). Global variables are available throughout a workspace and have the broadest scope in Postman.
  - name: Group Provisioning
    description: The **Group Provisioning** endpoints enable you to provision and manage your Postman groups.
  - name: Import
    description: The **Import** endpoints enable you to manage [importing and exporting](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/) Postman data.
  - name: Mocks
    description: The **Mocks** endpoints enable you to manage your [mock servers](https://learning.postman.com/docs/designing-and-developing-your-api/mocking-data/setting-up-mock/).
  - name: Monitors
    description: The **Monitors** endpoints enable you to manage your [monitors](https://learning.postman.com/docs/monitoring-your-api/intro-monitors/).
  - name: Private API Network
    description: The **Private API Network** endpoints enable you to manage and work with your team's [Private API Network](https://learning.postman.com/docs/collaborating-in-postman/adding-private-network/). These endpoints are only available on Postman [**Enterprise** plans](https://www.postman.com/pricing/#enterprise-solutions).
  - name: Pull Requests
    description: These endpoints enable you to manage your [pull requests](https://learning.postman.com/docs/collaborating-in-postman/using-version-control/creating-pull-requests/) in Postman. Pull requests allow reviewers to look at your changes. Reviewers can make comments on your changes and will decide whether to approve them and merge them into the parent element.
  - name: Roles
    description: The **Roles** endpoints enable you to manage user roles. [Roles])(https://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/) define user permissions within a Postman workspace.
  - name: Schema
    description: The **Schema** endpoints enable you to manage your API definitions. These endpoints also support multi-file schema.
  - name: SCIM
    description: |
      Postman supports [SCIM](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/) (System for Cross-domain Identity Management), which allows you to automate your team's provisioning. You can deploy Postman at scale across your organization and control access to it with your identity provider.

      SCIM provisioning is only available with a Postman [**Enterprise** plan](https://www.postman.com/pricing).

      **Note:**

      - While all other endpoints in this collection require a Postman API key, **these endpoints require a [SCIM API key](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/#generating-scim-api-key)**.
      - You must be a [Team Admin](http://learning.postman.com/docs/collaborating-in-postman/roles-and-permissions/#team-roles) to enable SCIM.
      - To use SCIM, you must have only **one** SSO method configured. If you have more than one SSO method enabled, you cannot generate an SCIM API key.
      - You can only deactivate users with the SCIM API. You cannot permanently delete users with the API.
      - You must [configure SSO](https://learning.postman.com/docs/administration/sso/admin-sso/) and [enable SCIM](http://learning.postman.com/docs/administration/managing-your-team/configuring-scim/#enabling-scim-provisioning) for your Postman team to use these endpoints.

      ### Rate limits

      For your organization's team, Postman applies per-minute rate limits across all SCIM API endpoints. This helps ensure that you have the best experience using Postman's SCIM API. The rate limits apply as follows:
      - **Write (POST, PUT, PATCH)** — 180 requests per minute.
      - **Read (GET)** — 300 requests per minute.

      If you reach the rate limit, the API will return an HTTP `429 Too Many Requests` response.
  - name: Secret Scanner
    description: The **Secret Scanner** endpoints enable you to manage the secrets detected by Postman's [Secret Scanner](https://learning.postman.com/docs/administration/secret-scanner/). These endpoints are only available on [**Enterprise** plans](https://www.postman.com/pricing/#enterprise-solutions) with the **Advanced Security Administration** add-on feature.
  - name: Transfer Collection Items
    description: The **Transfer Collection Items** endpoints enable you to move collection items between different collections or folders.
  - name: User
    description: The **User** endpoints enables you to manage information about the authenticated user.
  - name: User Provisioning
    description: |
      The **User Provisioning** endpoints enable you to provision and manage your Postman users.

      - You can only deactivate users with the SCIM API. You cannot permanently delete users with the API.
      - Users created with the SCIM API are automatically created in Postman:
        - If the account's email ID does not exist, the user is also added to their organization's Postman team.
        - If the account's email ID already exists, the system sends the user an email invite to join the Postman team. After they accept the invite, the are added to the team.
      - By default, new users are given the developer role in Postman. Postman user roles cannot be updated via the SCIM API. You must manage user and group roles in Postman.
  - name: Webhooks
    description: The **Webhooks** endpoints enable you to manage [custom webhooks](https://learning.postman.com/docs/running-collections/collection-webhooks/).
  - name: Workspace Tags
    description: The **Workspace Tags** endpoints enable you to manage workspace tags with Postman's [tagging](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/managing-workspaces/#tagging-a-workspace) feature. Tagging is available on Postman  [**Enterprise** plans](https://www.postman.com/pricing/).
  - name: Workspaces
    description: The **Workspaces** endpoints enable you to manage your [workspaces](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/creating-workspaces/). The Workspaces endpoints let you manage your workspaces. Workspaces enable you to organize your Postman work and collaborate with teammates.
paths:
  /accounts:
    get:
      summary: APIs.io Engineering Platform Get accounts
      description: Gets Postman billing account details for the given team.
      operationId: getAccounts
      tags:
        - Billing
      responses:
        '200':
          $ref: '#/components/responses/getAccounts'
        '400':
          $ref: '#/components/responses/invoicesNoTeam400Error'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
  /accounts/{accountId}/invoices:
    get:
      summary: APIs.io Engineering Platform List account invoices
      description: Gets all invoices for a Postman billing account filtered by the status of the invoice.
      operationId: getAccountInvoices
      tags:
        - Billing
      responses:
        '200':
          $ref: '#/components/responses/getAccountInvoices'
        '400':
          $ref: '#/components/responses/invoiceMissingStatus400Error'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/invoicesForbidden403Error'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
      parameters:
        - $ref: '#/components/parameters/billingAccountId'
        - $ref: '#/components/parameters/billingAccountStatus'
  /apis:
    get:
      summary: APIs.io Engineering Platform Get all APIs
      description: Gets information about all APIs in a workspace.
      operationId: getApis
      tags: []
      responses:
        '200':
          $ref: '#/components/responses/getApis'
        '401':
          $ref: '#/components/responses/common401Error'
        '403':
          $ref: '#/components/responses/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/api404ErrorNotFound'
        '422':
          $ref: '#/components/responses/v9Unsupported'
        '500':
          $ref: '#/components/responses/common500Error'
      parameters:
        - $ref: '#/components/parameters/workspaceIdQueryTrue'
        - $ref: '#/components/parameters/createdBy'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/apiDescription'
        - $ref: '#/components/parameters/limit'
    post:
      summary: APIs.io Engineering Platform Create an API
      description: Creates an API.
      operationId: createApi
      tags: []
      requestBody:
        $ref: '#/components/requestBodies/createApi'
      responses:
        '200':
          $ref: '#/components/responses/createApi'
        '400':
          $ref: '#/components/responses/workspace400ErrorParamMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/api403ErrorForbidden'
                  - $ref: '#/components/schemas/api403ErrorLimitReached'
                  - $ref: '#/components/schemas/featureUnavailable403Error'
              examples:
                Forbidden:
                  $ref: '#/components/examples/api403ErrorForbidden'
                API Limit Reached:
                  $ref: '#/components/examples/api403ErrorLimitReached'
                Feature Unavailable:
                  $ref: '#/components/examples/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/workspace404Error'
        '500':
          $ref: '#/components/responses/common500Error'
    parameters:
      - $ref: '#/components/parameters/workspaceIdQueryTrue'
      - $ref: '#/components/parameters/v10Accept'
  /apis/{apiId}:
    get:
      summary: APIs.io Engineering Platform 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.
      operationId: getApi
      tags: []
      responses:
        '200':
          $ref: '#/components/responses/getApi'
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/api404ErrorNotFound'
        '422':
          $ref: '#/components/responses/v9Unsupported'
        '500':
          $ref: '#/components/responses/common500Error'
      parameters:
        - $ref: '#/components/parameters/apiInclude'
    put:
      summary: APIs.io Engineering Platform Update an API
      description: Updates an API.
      operationId: updateApi
      tags: []
      requestBody:
        $ref: '#/components/requestBodies/updateApi'
      responses:
        '200':
          $ref: '#/components/responses/updateApi'
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/api403ErrorAndFeatureUnavailable'
        '404':
          $ref: '#/components/responses/api404ErrorNotFound'
        '422':
          $ref: '#/components/responses/v9Unsupported'
        '500':
          $ref: '#/components/responses/common500Error'
    delete:
      summary: APIs.io Engineering Platform Delete an API
      description: Deletes an API. On success, this returns an HTTP `204 No Content` response.
      operationId: deleteApi
      tags: []
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/api403ErrorAndFeatureUnavailable'
        '404':
          $ref: '#/components/responses/api404ErrorNotFound'
        '422':
          $ref: '#/components/responses/v9Unsupported'
        '500':
          $ref: '#/components/responses/common500Error'
    parameters:
      - $ref: '#/components/parameters/apiId'
      - $ref: '#/components/parameters/v10Accept'
  /apis/{apiId}/collections:
    post:
      summary: APIs.io Engineering Platform Add a collection
      description: |
        Adds a collection to an API. To do this, use the following `operationType` values:

        - `COPY_COLLECTION` — Copies a collection from the workspace and adds it to an API.
        - `CREATE_NEW` — Creates a new collection by providing the new collection's content.
        - `GENERATE_FROM_SCHEMA` — Generates the collection from an API schema.
            - `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.
      operationId: addApiCollection
      tags:
        - Collections
      requestBody:
        $ref: '#/components/requestBodies/addApiCollection'
      responses:
        '200':
          $ref: '#/components/responses/addApiCollection'
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/apiSchema403ErrorForbidden'
                  - $ref: '#/components/schemas/featureUnavailable403Error'
              examples:
                Forbidden:
                  $ref: '#/components/examples/apiSchema403ErrorForbidden'
                Feature Unavailable:
                  $ref: '#/components/examples/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/api404ErrorNotFound'
        '500':
          $ref: '#/components/responses/common500Error'
    parameters:
      - $ref: '#/components/parameters/apiId'
      - $ref: '#/components/parameters/v10Accept'
  /apis/{apiId}/collections/{collectionId}:
    get:
      summary: APIs.io Engineering Platform 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.
      operationId: getApiCollection
      tags:
        - Collections
      responses:
        '200':
          $ref: '#/components/responses/getApiCollection'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/api400ErrorVersionIdMissing'
                  - $ref: '#/components/schemas/v10HeaderMissing'
              examples:
                Version ID Missing:
                  $ref: '#/components/examples/api400ErrorVersionIdMissing'
                Missing v10 Accept Header:
                  $ref: '#/components/examples/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/api403ErrorAndFeatureUnavailable'
        '404':
          $ref: '#/components/responses/apiCollection404ErrorNotFound'
        '422':
          $ref: '#/components/responses/gitLinkedApi422Error'
        '500':
          $ref: '#/components/responses/common500Error'
      parameters:
        - $ref: '#/components/parameters/apiVersionQuery'
    parameters:
      - $ref: '#/components/parameters/apiId'
      - $ref: '#/components/parameters/collectionIdApi'
      - $ref: '#/components/parameters/v10Accept'
  /apis/{apiId}/collections/{collectionId}/sync-with-schema-tasks:
    put:
      summary: APIs.io Engineering Platform 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.
      operationId: syncCollectionWithSchema
      tags:
        - Collections
      responses:
        '202':
          $ref: '#/components/responses/syncCollectionWithSchema'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/apiCollection400InvalidParam'
                  - $ref: '#/components/schemas/v10HeaderMissing'
              examples:
                Invalid Parameter:
                  $ref: '#/components/examples/apiCollection400InvalidParam'
                Missing v10 Accept Header:
                  $ref: '#/components/examples/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/api401ErrorUnauthorized'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/apiSchema403ErrorForbidden'
                  - $ref: '#/components/schemas/featureUnavailable403Error'
              examples:
                Forbidden:
                  $ref: '#/components/examples/apiSchema403ErrorForbidden'
                Feature Unavailable:
                  $ref: '#/components/examples/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/apiSchema404ErrorNotFound'
        '422':
          $ref: '#/components/responses/apiSchema422ErrorActionNotAllowed'
        '500':
          $ref: '#/components/responses/common500Error'
    parameters:
      - $ref: '#/components/parameters/apiId'
      - $ref: '#/components/parameters/collectionIdApi'
      - $ref: '#/components/parameters/v10Accept'
  /apis/{apiId}/comments:
    get:
      summary: APIs.io Engineering Platform Get an API's comments
      description: Gets all comments left by users in an API.
      operationId: getApiComments
      tags:
        - Comments
      responses:
        '200':
          $ref: '#/components/responses/commentGet'
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/comment401Error'
        '403':
          $ref: '#/components/responses/comment403ErrorAndFeatureUnavailable'
        '404':
          $ref: '#/components/responses/comment404Error'
        '500':
          $ref: '#/components/responses/comment500Error'
    post:
      summary: APIs.io Engineering Platform Create an API comment
      description: |
        Creates a comment on an API.

        **Note:**

        This endpoint accepts a max of 10,000 characters.
      tags:
        - Comments
      operationId: createApiComment
      requestBody:
        $ref: '#/components/requestBodies/commentCreateUpdate'
      responses:
        '201':
          $ref: '#/components/responses/commentCreated'
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/comment401Error'
        '403':
          $ref: '#/components/responses/comment403ErrorAndFeatureUnavailable'
        '404':
          $ref: '#/components/responses/comment404Error'
        '500':
          $ref: '#/components/responses/comment500Error'
    parameters:
      - $ref: '#/components/parameters/apiId'
  /apis/{apiId}/comments/{commentId}:
    put:
      summary: APIs.io Engineering Platform Update an API's comment
      description: |
        Updates a comment on an API.

        **Note:**

        This endpoint accepts a max of 10,000 characters.
      operationId: updateApiComment
      tags:
        - Comments
      requestBody:
        $ref: '#/components/requestBodies/commentCreateUpdate'
      responses:
        '200':
          $ref: '#/components/responses/commentUpdated'
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/comment401Error'
        '403':
          $ref: '#/components/responses/comment403ErrorAndFeatureUnavailable'
        '404':
          $ref: '#/components/responses/comment404Error'
        '500':
          $ref: '#/components/responses/comment500Error'
    delete:
      summary: APIs.io Engineering Platform Delete an API's comment
      description: |
        Deletes a comment from an API. 

# --- truncated at 32 KB (828 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/engineering-platform/refs/heads/main/openapi/_original/postman-openapi-original.yml