openapi: 3.0.1
info:
  title: Cisco Umbrella Tagging API
  version: 2.0.0
  description: Manage the tags and roaming computers with tags in the Umbrella organization.
  contact:
    name: Cloud Security Developer Community

tags:
  - name: Tags
    description: Manage the tags in the organization.
  - name: TagDevices
    description: Manage the roaming computers in the Umbrella organization that have a tag.
  - name: Umbrella

servers:
  - url: https://api.umbrella.com/{basePath}
    variables:
      basePath:
        default: deployments/v2

security:
  - oauthFlow: []

paths:

  /tags:
    get:
      description: List the tags in the organization.
      summary: Get Tags
      operationId: getTags
      tags:
        - Tags
        - Umbrella
      security:
        - oauthFlow:
          - deployments.tags:read
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/tagInformation'
              # returns an empty array if no tags found
              example:
                - id: 67747
                  organizationId: 3056800
                  name: tag-two
                  originsModifiedAt: '2022-04-12T23:20:50.52Z'
                  createdAt: '2022-04-12T23:20:50.52Z'
                  modifiedAt: '2022-04-12T23:20:50.52Z'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
    post:
      description: Add a tag to the organization.
      summary: Add Tag
      operationId: createTag
      tags:
        - Tags
        - Umbrella
      security:
        - oauthFlow:
          - deployments.tags:write
      requestBody:
        $ref: '#/components/requestBodies/name'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tagInformation'
              example:
                id: 67747
                organizationId: 3056800
                name: test-tag-name
                originsModifiedAt: '2022-04-12T23:20:50.52Z'
                createdAt: '2022-04-12T23:20:50.52Z'
                modifiedAt: '2022-04-12T23:20:50.52Z'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

  /tags/{tagId}/devices:
    get:
      description: List the roaming computers that have a tag with the specified tag ID.
      summary: Get Devices With Tag
      operationId: getDevicesWithTag
      tags:
        - TagDevices
        - Umbrella
      security:
        - oauthFlow:
            - deployments.tagDevices:read
      parameters:
        - $ref: '#/components/parameters/limitTagDevices'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/tagId'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/deviceInformation'
              example:
                - originId: 384428946
                  organizationId: 3056800
                  label: test1
                  type: 'roaming/anyconnect'
                  createdAt: '2022-04-12T23:20:50.52Z'
                  modifiedAt: '2022-04-12T23:20:50.52Z'
                - originId: 12345
                  organizationId: 567893
                  label: device-one
                  type: linux
                  createdAt: '2022-04-12T23:20:50.52Z'
                  modifiedAt: '2022-04-12T23:20:50.52Z'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404TagNotFound'
        '500':
          $ref: '#/components/responses/500Error'
    post:
      description: For the tag ID, add the tag to the roaming computers.
      summary: Add Tag to Devices
      operationId: addTagToDevices
      tags:
        - TagDevices
        - Umbrella
      security:
        - oauthFlow:
            - deployments.tagDevices:write
      parameters:
        - $ref: '#/components/parameters/tagId'
      requestBody:
        $ref: '#/components/requestBodies/addOrigins'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taggedDeviceInformation'
              example:
                tagId: 67343
                addOrigins:
                  - 12321231
                  - 123134314
                removeOrigins:
                  - 12345678
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404TagNotFound'
        '500':
          $ref: '#/components/responses/500Error'

    delete:
      description: |-
        For the tag ID, remove the tag on the roaming computers in the organization.
        After the delete, if the tag is not assigned to any roaming computers in the organization, Umbrella removes the tag from
        the organization. You can recreate the tag for your organization.
      summary: Delete Tag on Devices
      operationId: deleteTagOnDevices
      tags:
        - TagDevices
        - Umbrella
      security:
        - oauthFlow:
          - deployments.tagDevices:write 
      parameters:
        - $ref: '#/components/parameters/tagId'
      requestBody:
        $ref: '#/components/requestBodies/removeOrigins'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/taggedDeviceInformation'
              example:
                - tagId: 67343
                  addOrigins:
                   - 12345678
                  removeOrigins:
                    - 12321231
                    - 123134314
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'

components:

  headers:
    Content-Type:
      schema:
        type: string
      description: The MIME content type of the response body.
      example: application/json
    Date:
      schema:
        type: string
        pattern: '^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$'
      description: The timestamp of the response.
      example: '2023-03-14T18:34:25Z'
      #'2023-03-14T18:34:25.412525046Z'

  parameters:
    tagId:
      name: tagId
      in: path
      description: The ID of the tag.
      required: true
      schema:
        type: integer
      example: 2

    page:
      name: page
      description: The number of a page in the collection.
      schema:
        type: integer
        default: 1
      in: query
      required: false
      example: 2

    limitTagDevices:
      name: limit
      description: The number of roaming computers with the tag ID to return from the collection in the response.
      schema:
        type: integer
        default: 10
        maximum: 500
      in: query
      required: false
      example: 350

  requestBodies:

    name:
      description: Add the tag to the devices in the organization.
      content:
        application/json:
          schema:
            type: object
            description: The name of the tag.
            required:
              - name
            properties:
              name:
                type: string
                minLength: 1
                maxLength: 16
                description: The name of the tag.
                example: test-tag-name
          example:
            name: test-tag-name

    removeOrigins:
      description: |-
        Remove the tag on the roaming computers. Provide a list of roaming computer origin IDs.
        The request body can include at most 500 origin IDs.
      content:
        application/json:
          schema:
            type: object
            properties:
              removeOrigins:
                $ref: '#/components/schemas/removeOrigins'
          example:
            removeOrigins:
              - 12321231
              - 123134314

    addOrigins:
      description: |-
        Add the tag to the roaming computers. Provide a list of roaming computer origin IDs.
        The request body can include at most 500 origin IDs.
      content:
        application/json:
          schema:
            type: object
            properties:
              addOrigins:
                $ref: '#/components/schemas/addOrigins'
          example:
            addOrigins:
              - 12321231
              - 123134314

  schemas:

    id:
      type: integer
      description: The unique ID of the tag.
      example: 12345678

    originId:
      type: integer
      description: The unique identifier of the device.
      example: 2456

    tagId:
      type: integer
      description: The unique ID of the tag.
      example: 12345678

    label:
      type: string
      description: The display name of the device.
      example: device-one

    name:
      type: string
      description: The name of the tag.
      example: tag-one

    type:
      type: string
      description: The device type.
      example: macOS

    organizationId:
      type: integer
      description: The organization ID.
      example: 2456789

    originsModifiedAt:
      type: string
      format: date-time
      description: |-
        The date and time (timestamp) that Umbrella modified the roaming computers.
        The timestamp is an ISO 8601 formatted string. For example: `2023-04-12T23:20:50.52Z`.
      example: '2022-04-12T23:20:50.52Z'

    createdAt:
      type: string
      format: date-time
      description: |-
        The date and time (timestamp) that Umbrella added the tag to the roaming computer.
        The timestamp is an ISO 8601 formatted string. For example: `2023-04-12T23:20:50.52Z`.
      example: '2022-04-12T23:20:50.52Z'

    modifiedAt:
      type: string
      format: date-time
      description: |-
        The date and time (timestamp) that Umbrella updated the tag on the roaming computer.
        The timestamp is an ISO 8601 formatted string. For example: `2023-04-12T23:20:50.52Z`.
      example: '2022-04-12T23:20:50.52Z'

    deviceCreatedAt:
      type: string
      format: date-time
      description: |-
        The date and time (timestamp) that Umbrella added the roaming computer to the organization.
        The timestamp is an ISO 8601 formatted string. For example: `2023-04-12T23:20:50.52Z`.
      example: '2022-04-12T23:20:50.52Z'

    deviceModifiedAt:
      type: string
      format: date-time
      description: |-
        The date and time (timestamp) that Umbrella updated the roaming computer in the organization.
        The timestamp is an ISO 8601 formatted string. For example: `2023-04-12T23:20:50.52Z`.
      example: '2022-04-12T23:20:50.52Z'

    addOrigins:
      type: array
      description: The list of roaming computers (origin IDs) that have the tag.
      items:
        type: integer
        description: An origin ID.
        example: 12345678
      example:
        - 12345678
        - 87654321

    removeOrigins:
      type: array
      description: The list of roaming computers (origin IDs) that have the tag removed.
      items:
        type: integer
        description: An origin Id.
        example: 12345678
      example:
        - 12345678
        - 87654321

    deviceInformation:
      type: object
      description: The information about the device.
      required: 
        - originId
        - organizationId
        - label
        - type
        - createdAt
        - modifiedAt
      properties:
        originId:
          $ref: '#/components/schemas/originId'
        organizationId:
          $ref: '#/components/schemas/organizationId'
        label:
          $ref: '#/components/schemas/label'
        type:
          $ref: '#/components/schemas/type'
        createdAt:
          $ref: '#/components/schemas/deviceCreatedAt'
        modifiedAt:
          $ref: '#/components/schemas/deviceModifiedAt'
      example:
        originId: 12345
        organizationId: 567893
        label: device-one
        type: linux
        createdAt: '2022-04-12T23:20:50.52Z'
        modifiedAt: '2022-04-12T23:20:50.52Z'

    tagInformation:
      type: object
      description: The tag information for the device.
      required:
        - id
        - organizationId
        - name
        - originsModifiedAt
        - createdAt
        - modifiedAt
      properties:
        id:
          $ref: '#/components/schemas/id'
        organizationId:
          $ref: '#/components/schemas/organizationId'
        name:
          $ref: '#/components/schemas/name'
        originsModifiedAt:
          $ref: '#/components/schemas/originsModifiedAt'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        modifiedAt:
          $ref: '#/components/schemas/modifiedAt'
      example:
        id: 12345
        organizationId: 567893
        name: tag-one
        originsModifiedAt: '2022-04-12T23:20:50.52Z'
        createdAt: '2022-04-12T23:20:50.52Z'
        modifiedAt: '2022-04-12T23:20:50.52Z'

    taggedDeviceInformation:
      type: object
      description: |-
        The information about the tagged devices:
        tag ID, origin IDs in the organization that have the tag on the roaming computers, and 
        origin IDs in the organization that have the tag removed from the roaming computers.
      required:
        - tagId
        - addOrigins
        - removeOrigins
      properties:
        tagId:
          $ref: '#/components/schemas/tagId'
        addOrigins:
          $ref: '#/components/schemas/addOrigins'
        removeOrigins:
          $ref: '#/components/schemas/removeOrigins'

  securitySchemes:

    oauthFlow:
      type: oauth2
      description: client credential flow
      flows:
        clientCredentials:
          tokenUrl: https://api.umbrella.com/auth/v2/token
          scopes:
            deployments.tags:read: Tags read access
            deployments.tags:write: Tags write access
            deployments.tagDevices:read: Tagged devices read access
            deployments.tagDevices:write: Tagged devices write access

  responses:
    400Error:
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              Error:
                type: string
    401Error:
      description: Unauthorized
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              Error:
                type: string
    403Error:
      description: Forbidden
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              Error:
                type: string
    404Error:
      description: Not Found
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              Error:
                type: string
    404TagNotFound:
      description: Tag Not found
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            required:
              - Error
            properties:
              Error:
                type: string
            example:
              Error: object_not_found
              message: Tag not found
              code: 404
              code_text: Not Found
    500Error:
      description: Internal Server Error
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              Error:
                type: string
