PagerDuty Change Tags API

openapi: 3.2.0
info:
  description: 'This document describes the PagerDuty REST APIs.


    For guides and examples please visit our [Documentation.](https://developer.pagerduty.com/docs/get-started/getting-started/)


    Our REST APIs are defined in OpenAPI v3.x. You can view the schema at [github.com/PagerDuty/api-schema](https://github.com/PagerDuty/api-schema).


    Note that properties in some schemas have fields not shown by default such as `readOnly`, `format`, and `default`. Hover your cursor over the right column that looks like `optional+1` to see the full list of fields.

    '
  contact:
    name: PagerDuty Support
    url: http://www.pagerduty.com/support
    email: support@pagerduty.com
  title: PagerDuty Abilities Change Tags API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Change Tags
paths:
  /{entity_type}/{id}/change_tags:
    post:
      x-pd-requires-scope: tags.write
      tags:
      - Change Tags
      operationId: createEntityTypeByIdChangeTags
      description: 'Assign existing or new tags.


        A Tag is applied to Escalation Policies, Teams or Users and can be used to filter them.


        For more information see the [API Concepts Document](../../api-reference/ZG9jOjI3NDc5Nzc-api-concepts#tags)


        Scoped OAuth requires: `tags.write`

        '
      summary: PagerDuty Assign tags
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/entity_type'
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Tags to add to or remove from the entity.
              properties:
                add:
                  type: array
                  description: 'Array of tags and/or tag references to add to the entity.

                    For elements with type `tag_reference`, the tag with the corresponding `id` is added to the entity.

                    For elements with type `tag`, if there is an existing tag with the given

                    label that tag is added to the entity. If there is no existing tag with that label and the user has permission

                    to create tags, a new tag is created with that label and assigned to the entity.

                    '
                  items:
                    title: Tags to add
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - tag
                        - tag_reference
                      label:
                        type: string
                        description: The label of the tag. Should be used when type is "tag".
                        maxLength: 191
                      id:
                        type: string
                        description: The id of the tag. Should be used when type is "tag_reference".
                        readOnly: true
                    required:
                    - type
                remove:
                  type: array
                  description: Array of tag references to remove from the entity.
                  items:
                    title: Tags to remove.
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - tag_reference
                      id:
                        type: string
                        description: The id of the tag
                        readOnly: true
                    required:
                    - type
                    - id
            examples:
              tags:
                summary: Request Example
                value:
                  add:
                  - type: tag
                    label: Batman
                  - type: tag_reference
                    id: P5IYCNZ
                  remove:
                  - type: tag_reference
                    id: POE7RY8
                  - type: tag_reference
                    id: PG68P1M
      responses:
        '200':
          description: The tags were added and/or removed.
          content:
            application/json:
              schema:
                type: object
              examples:
                response:
                  summary: Request Example
                  value:
                    add:
                    - type: tag
                      label: Batman
                    - type: tag_reference
                      id: P5IYCNZ
                    remove:
                    - type: tag_reference
                      id: POE7RY8
                    - type: tag_reference
                      id: PG68P1M
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Conflict:
      description: The request conflicts with the current state of the server.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: integer
                    readOnly: true
                  message:
                    type: string
                    readOnly: true
                    description: Error message string
                  errors:
                    type: array
                    readOnly: true
                    items:
                      type: string
                      readOnly: true
                      description: Human-readable error details
                example:
                  message: Not Found
                  code: 2100
    Unauthorized:
      description: 'Caller did not supply credentials or did not provide the correct credentials.

        If you are using an API key, it may be invalid or your Authorization header may be malformed.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    TooManyRequests:
      description: Too many requests have been made, the rate limit has been reached.
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    Forbidden:
      description: 'Caller is not authorized to view the requested resource.

        While your authentication is valid, the authenticated user or token does not have permission to perform this action.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    ArgumentError:
      description: Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
  parameters:
    entity_type:
      name: entity_type
      in: path
      description: Type of entity related with the tag
      required: true
      schema:
        type: string
        enum:
        - users
        - teams
        - escalation_policies
    header_Accept:
      name: Accept
      description: The `Accept` header is used as a versioning header.
      in: header
      required: true
      schema:
        type: string
        default: application/vnd.pagerduty+json;version=2
    id:
      name: id
      description: The ID of the resource.
      in: path
      required: true
      schema:
        type: string
    header_Content-Type:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
        enum:
        - application/json
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
      description: The API Key with format `Token token=<API_KEY>`