APIs.io Engineering Platform API Tags API

openapi: 3.2.0
info:
  title: APIs.io Engineering Platform Postman API Tags API
  description: "The Postman API enables you to programmatically access data stored in your Postman account.\n\n> Certain endpoints may be unavailable depending on your region and/or Postman plan.\n\nFor 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).\n\n## Getting started\n\nYou can get started with the Postman API by creating a copy of this definition in your workspace.\n\n### EU users\n\nFor 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.\n\n## About the Postman API\n\n- You must use a valid API Key to send requests to the API endpoints.\n- The API has [rate and usage limits](https://learning.postman.com/docs/developer/postman-api/postman-api-rate-limits/).\n- The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP `301` redirect to the corresponding HTTPS resources.\n- 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.\n- 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.\n- 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.\n- When calling the API Builder endpoints, you must send an `Accept` header with the `application/vnd.api.v10+json` value.\n\n### IDs and UIDs\n\nAll items in Postman, such as collections, workspaces, and APIs, have IDs and UIDs:\n\n- An ID is the unique ID assigned to a Postman item. For example, `ec29121c-5203-409f-9e84-e83ffc10f226`.\n- 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:\n    - `12345678` is the user's ID.\n    - `ec29121c-5203-409f-9e84-e83ffc10f226` is the item's ID.\n\n### Enum values\n\nAny documented enum values should be considered partial lists and may change over time.\n\n### 403 response for unavailable features\n\nDepending 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.\n\n### 503 response\n\nAn 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.\n\nIf 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/).\n\n## Authentication\n\nPostman 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.\n\nYou 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.\n\n### SCIM authentication\n\nWhile 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).\n\n### Authentication error response\n\nIf an API key is missing, malformed, or invalid, you will receive an HTTP `401 Unauthorized` response code.\n\n## Rate and usage limits\n\nAPI 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/).\n\nWhen 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:\n\n- `rateLimited` — Rate limits reached. The response returns the time after which you can resume calls to the Postman API.\n- `serviceLimitExhausted` — Postman API service limits reached. You will need to contact your Postman Team Admin for assistance.\n\n## Support\n\nFor help regarding accessing the Postman API, you can:\n\n- Visit [Postman Support](https://support.postman.com/hc/en-us) or our [Community and Support](https://www.postman.com/community/) sites.\n- Reach out to the [Postman community](https://community.postman.com/).\n- Submit a help request to [Postman support](https://support.postman.com/hc/en-us/requests/new/).\n\n## Policies\n\n- [Postman Terms of Service](http://www.postman.com/legal/terms/)\n- [Postman Privacy Policy](https://www.postman.com/legal/privacy-policy/)\n"
  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 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/).
paths:
  /apis/{apiId}/tags:
    parameters:
    - $ref: '#/components/parameters/apiId'
    - $ref: '#/components/parameters/v10Accept'
    get:
      summary: APIs.io Engineering Platform Get an API's tags
      description: Gets all the tags associated with an API.
      operationId: getApiTags
      tags:
      - API Tags
      responses:
        '200':
          $ref: '#/components/responses/tagGetPut'
        '400':
          $ref: '#/components/responses/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/tag401Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/tag403Error'
                - $ref: '#/components/schemas/featureUnavailable403Error'
              examples:
                Forbidden:
                  $ref: '#/components/examples/tag403Error'
                Feature Unavailable:
                  $ref: '#/components/examples/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/tag404Error'
        '500':
          $ref: '#/components/responses/tag500Error'
    put:
      summary: APIs.io Engineering Platform Update an API's tags
      description: Updates an API's associated tags. This endpoint replaces all existing tags with those you pass in the request body.
      operationId: updateApiTags
      tags:
      - API Tags
      requestBody:
        $ref: '#/components/requestBodies/tagUpdateTags'
      responses:
        '200':
          $ref: '#/components/responses/tagGetPut'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/tag400Error'
                - $ref: '#/components/schemas/v10HeaderMissing'
              examples:
                Bad Request:
                  $ref: '#/components/examples/tag400Error'
                Missing v10 Accept Header:
                  $ref: '#/components/examples/v10HeaderMissing'
        '401':
          $ref: '#/components/responses/tag401Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/tag403Error'
                - $ref: '#/components/schemas/featureUnavailable403Error'
              examples:
                Forbidden:
                  $ref: '#/components/examples/tag403Error'
                Feature Unavailable:
                  $ref: '#/components/examples/featureUnavailable403Error'
        '404':
          $ref: '#/components/responses/tag404Error'
        '500':
          $ref: '#/components/responses/tag500Error'
components:
  examples:
    tag403Error:
      value:
        type: https://api.postman.com/problems/forbidden
        title: Access Denied
        detail: The tags feature is only available to enterprise teams
        status: 403
    tag400Error:
      value:
        title: Bad Request
        detail: body/tags/0/slug must NOT have more than 64 characters
        status: 400
    featureUnavailable403Error:
      value:
        type: https://api.postman.com/problems/forbidden
        title: Forbidden
        detail: This feature isn't available in your region.
        status: 403
    v10HeaderMissing:
      value:
        name: instanceNotFoundError
        message: API not found. For v10 and later APIs, ensure that your request sends the "application/vnd.api.v10+json" Accept header.
  schemas:
    tag400Error:
      title: Bad Request
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
          example: https://api.postman.com/problems/badrequest
        title:
          type: string
          description: A short summary of the problem.
          example: Bad Request
        detail:
          type: string
          description: Information about the error.
          example: body/tags/0/slug must NOT have more than 64 characters
        status:
          type: integer
          format: http-status-code
          description: The error's HTTP status code.
          example: 400
    tag401Error:
      title: Unauthorized
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
          example: https://api.postman.com/problems/unauthorized
        title:
          type: string
          description: A short summary of the problem.
          example: Unauthorized
        detail:
          type: string
          description: Information about the error.
          example: The request lacks valid credentials.
        status:
          type: integer
          format: http-status-code
          description: The error's HTTP status code.
          example: 401
    tag403Error:
      title: Forbidden
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
          example: https://api.postman.com/problems/forbidden
        title:
          type: string
          description: A short summary of the problem.
          example: Access Denied
        detail:
          type: string
          description: Information about the error.
          example: The tags feature is only available to enterprise teams
        status:
          type: integer
          format: http-status-code
          description: The error's HTTP status code.
          example: 403
    tag500Error:
      title: Unexpected Error
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
          example: https://api.postman.com/problems/internal-server-error
        title:
          type: string
          description: A short summary of the problem.
          example: Something went wrong
        detail:
          type: string
          description: Information about the error.
          example: Something went wrong while fetching entities having the provided slug.
        status:
          type: integer
          format: http-status-code
          description: The error's HTTP status code.
          example: 500
        instance:
          type: string
          example: /tags/hello-world/entities
          description: The URI reference that identifies the specific occurrence of the problem.
    tag404Error:
      title: Not Found
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
          example: https://api.postman.com/problems/not-found
        title:
          type: string
          description: A short summary of the problem.
          example: Resource Not Found
        detail:
          type: string
          description: Information about the error.
          example: Slug 'needs-review' does not exist.
        status:
          type: integer
          format: http-status-code
          description: The error's HTTP status code.
          example: 404
        instance:
          type: string
          description: The URI reference that identifies the specific occurrence of the problem.
          example: /tags/needs-review/entities
    featureUnavailable403Error:
      title: Feature Unavailable
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
          example: https://api.postman.com/problems/forbidden
        title:
          type: string
          description: A short summary of the problem.
          example: Forbidden
        detail:
          type: string
          description: Information about the error.
          example: This feature isn't available in your region.
        status:
          type: integer
          format: http-status-code
          description: The error's HTTP status code.
          example: 403
    tagGetPut:
      title: Success Response
      type: object
      properties:
        tags:
          type: array
          maxItems: 5
          minItems: 0
          description: A list of associated tags.
          items:
            type: object
            description: Information about the tag.
            properties:
              slug:
                type: string
                pattern: ^[a-z][a-z0-9-]*[a-z0-9]+$
                minLength: 2
                maxLength: 64
                description: The tag's ID within a team or individual (non-team) user scope.
                example: needs-review
    v10HeaderMissing:
      title: Missing v10 Accept Header
      type: object
      properties:
        name:
          type: string
          description: The error name.
          example: instanceNotFoundError
        message:
          type: string
          description: The error message.
          example: API not found. For v10 and later APIs, ensure that your request sends the "application/vnd.api.v10+json" Accept header.
  responses:
    v10HeaderMissing:
      description: Missing v10 Accept Header
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/v10HeaderMissing'
          examples:
            Missing v10 Accept Header:
              $ref: '#/components/examples/v10HeaderMissing'
    tag500Error:
      description: Unexpected Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/tag500Error'
          example:
            type: https://api.postman.com/problems/internal-server-error
            title: Something went wrong
            detail: Something went wrong while fetching entities having the provided slug.
            status: 500
            instance: /tags/needs-review/entities
    tag401Error:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/tag401Error'
          example:
            type: https://api.postman.com/problems/unauthorized
            title: Unauthorized
            detail: The request lacks valid credentials.
            status: 401
    tagGetPut:
      description: Success Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/tagGetPut'
          example:
            tags:
            - slug: needs-review
            - slug: test-api
    tag404Error:
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/tag404Error'
          example:
            type: https://api.postman.com/problems/not-found
            title: Resource Not Found
            detail: Slug 'needs-review' does not exist.
            status: 404
            instance: /tags/needs-review/entities
  parameters:
    apiId:
      name: apiId
      in: path
      required: true
      description: The API's ID.
      schema:
        type: string
        example: 90ca9f5a-c4c4-11ed-afa1-0242ac120002
    v10Accept:
      name: Accept
      in: header
      required: true
      description: The `application/vnd.api.v10+json` request header required to use the endpoint.
      schema:
        type: string
        enum:
        - application/vnd.api.v10+json
        example: application/vnd.api.v10+json
  requestBodies:
    tagUpdateTags:
      content:
        application/json:
          schema:
            title: Update Tags
            type: object
            required:
            - tags
            properties:
              tags:
                type: array
                minItems: 0
                maxItems: 5
                description: A list of the associated tags as slugs.
                items:
                  type: object
                  description: Information about the tag.
                  required:
                  - slug
                  properties:
                    slug:
                      type: string
                      pattern: ^[a-z][a-z0-9-]*[a-z0-9]+$
                      minLength: 2
                      maxLength: 64
                      description: The tag's ID within a team or individual (non-team) user scope.
                      example: needs-review
          example:
            tags:
            - slug: needs-review
  securitySchemes:
    PostmanApiKey:
      type: apiKey
      in: header
      name: x-api-key
    scimApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: A valid [SCIM API key](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/#generating-scim-api-key) for calls to SCIM endpoints.