Cisco Umbrella Tagging API
Manage the tags and roaming computers with tags in the Umbrella organization.
OpenAPI Specification
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
x-provenance:
method: harvested
authored_by: Cisco Umbrella
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
provider_published: true
source_host: pubhub.devnetcloud.com
note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously.
Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
x-evidence:
- type: source
url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
- type: source
url: https://developer.cisco.com/docs/cloud-security/
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'
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'
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:\ntag ID, origin IDs in the organization that have the tag on\
\ the roaming computers, and \norigin 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
x-provenance:
method: harvested
first_party: true
harvested: '2026-08-19'
source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/tagging.yaml
publisher: Cisco Systems, Inc. (Cisco DevNet Cloud Security docs)
x-evidence:
fetched: '2026-08-19'
url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/tagging.yaml
http_status: 200
docs: https://developer.cisco.com/docs/cloud-security/