openapi: 3.2.0 info: title: Cisco Catalyst Center Energy API version: 1.0.1 contact: name: Cisco TAC World Wide url: https://www.cisco.com/c/en/us/support/web/tsd-cisco-worldwide-contacts.html email: tac@cisco.com license: name: Cisco Catalyst Center License url: https://www.cisco.com/c/en/us/products/collateral/software/dna-software-ebook-cte.html termsOfService: https://www.cisco.com/c/en/us/about/legal/cloud-and-software/end_user_license_agreement.html description: 'Operations tagged energy across 2 of this provider''s published API definitions: cisco-catalyst-center-device-energy-openapi.yml, cisco-catalyst-center-sites-energy-openapi.yml. Each path carries the servers of the definition it was published in.' x-provenance: method: harvested authored_by: Cisco Catalyst Center harvested_by: API Evangelist harvested_on: '2026-08-19' first_party: true provider_published: true source_host: developer.cisco.com note: 27 Cisco-published OpenAPI 3.0 Assurance documents (185 operations). Ownership confirmed from the tac@cisco.com contact, the Cisco EULA terms-of-service URL and the Cisco Catalyst Center license block carried in each document. derived_view: Per-tag view of cisco-catalyst-center-device-energy-openapi.yml, the provider's source document. Operations and schemas are the provider's, unmodified; only the partition is ours. derived_from: cisco-catalyst-center-device-energy-openapi.yml operation_coverage: 12/19 x-evidence: - type: source url: https://developer.cisco.com/docs/catalyst-center/ - type: source url: https://developer.cisco.com/dnacenter/ servers: - url: https://developer.cisco.com/data/api/v1 tags: - name: energy description: Operations related to retrieving overall energy information for Catalyst Center Devices externalDocs: description: Catalyst Center Assurance user guide url: https://www.cisco.com/c/en/us/support/cloud-systems-management/dna-center/products-user-guide-list.html paths: /data/api/v1/energy/networkDevices: get: tags: - energy summary: Get devices energy description: Retrieves a list of network devices with energy data based on the specified query parameters. It returns the most recent snapshot of energy data within the provided start and end times. If no start and end times are specified, it defaults to returning the latest available energy data from the past 24 hours. operationId: readNetworkDevicesEnergy parameters: - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: limit in: query description: Maximum number of records to return schema: minimum: 1 type: integer default: 500 - name: cursor in: query description: It's an opaque string field indicating the next record in the requested collection. schema: type: string - name: sortBy in: query description: A field within the response to sort by. schema: type: string - name: order in: query description: The sort order of the field ascending or descending. schema: type: string default: asc enum: - asc - desc - name: id in: query description: 'The list of Device Uuids (e.g., `6bef213c-19ca-4170-8375-b694e251101c`). Examples: `id=6bef213c-19ca-4170-8375-b694e251101c` (single device requested) `id=6bef213c-19ca-4170-8375-b694e251101c&id=32219612-819e-4b5e-a96b-cf22aca13dd9` ' required: false style: form explode: true schema: type: array items: type: string - name: siteId in: query description: 'The UUID of the site. (Ex. `flooruuid`) Examples: `?siteId=id1` (single id requested) `?siteId=id1&siteId=id2&siteId=id3` (multiple ids requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchy in: query description: 'The full hierarchical breakdown of the site tree starting from Global site name and ending with the specific site name. The Root site is named "Global" (Ex. `Global/AreaName/BuildingName/FloorName`) This field supports wildcard asterisk (`*`) character search support. E.g. `*/San*, */San, /San*` Examples: `?siteHierarchy=Global/AreaName/BuildingName/FloorName` (single siteHierarchy requested) `?siteHierarchy=Global/AreaName/BuildingName/FloorName&siteHierarchy=Global/AreaName2/BuildingName2/FloorName2` (multiple siteHierarchies requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchyId in: query description: 'The full hierarchy breakdown of the site tree in id form starting from Global site UUID and ending with the specific site UUID. (Ex. `globalUuid/areaUuid/buildingUuid/floorUuid`) This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*` Examples: `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid `(single siteHierarchyId requested) `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid&siteHierarchyId=globalUuid/areaUuid2/buildingUuid2/floorUuid2` (multiple siteHierarchyIds requested) ' required: false style: form explode: true schema: type: array items: type: string - name: deviceCategory in: query description: "The list of device deviceCategories. \n\nExamples:\n\n`deviceCategory=Switch` (single device family\ \ requested)\n\n`deviceCategory=Switch&deviceCategory=Router` (multiple device categories with comma separator)\n" required: false style: form explode: true schema: type: array items: type: string format: string enum: - Switch - Router - name: deviceSubCategory in: query description: 'The list of device sub categories. Examples: `deviceSubCategory=Cisco Catalyst 9300 Series Switches` (single device family requested) `deviceSubCategory=Cisco Catalyst 9300 Series Switches&deviceSubCategory=Cisco Catalyst 9400 Series Switches` ' required: false style: form explode: true schema: type: array items: type: string format: string - name: view in: query description: 'List of views. View and attribute work in union. Each view will include its attributes. For example, view device includes all the attributes related to device. Please refer to `NetworkDeviceEnergyView` model for supported list of views Examples: `view=device&view=energy` ' required: false style: form explode: true schema: type: array items: type: string - name: attribute in: query description: "List of attributes. Please refer to `NetworkDeviceEnergyAttribute` for supported list of attributes\ \ \n\nExamples:\n`attribute=id&attribute=energyConsumed`\n" required: false style: form explode: true schema: type: array items: type: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent responses: '200': description: Devices Energy Summaries Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/NetworkDevicesEnergyResponse' example: response: - id: 8f741bdf-788c-48f7-8ab1-017a826e4521 deviceName: sda-c9k-100.cisco.com deviceCategory: Switches deviceSubCategory: Cisco Catalyst 9300 Series Switches siteId: 8f741bdf-788c-48f7-8ab1-017a826e4521 siteHierarchy: Global/Country1/Site1 siteHierarchyId: 8f741bdf-788c-48f7-8ab1-017a826e4521/8f741bdf-788c-48f7-8ab1-017a826e4521 energyConsumed: 2023 estimatedCost: 2524.23 estimatedEmission: 513 carbonIntensity: 123 page: limit: 10 cursor: eyJ1dWlkX3Rlcm1zIjoiZTBlM2VkMDgtNjE5OS00ZmVmLWFiNDEtZjA4OTcwMTMzYjdkIn0= count: 20 sortBy: - name: name order: asc version: '2.0' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/clients: get: tags: - energy summary: Get clients energy description: Retrieves a list of client devices with energy data based on the specified query parameters. It returns the most recent snapshot of energy data within the provided start and end times. If no start and end times are specified, it defaults to returning the latest available energy data from the past 24 hours. operationId: readClientDevicesEnergy parameters: - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: limit in: query description: Maximum number of records to return schema: minimum: 1 type: integer default: 500 - name: cursor in: query description: It's an opaque string field indicating the next record in the requested collection. schema: type: string - name: sortBy in: query description: A field within the response to sort by. schema: type: string - name: order in: query description: The sort order of the field ascending or descending. schema: type: string default: asc enum: - asc - desc - name: id in: query description: 'The list of Mac addresses (e.g., `54:9F:C6:43:FF:80`). Examples: `id=54:9F:C6:43:FF:80` (single device requested) `id=54:9F:C6:43:FF:80&id=01:23:45:67:89:AB` ' required: false style: form explode: true schema: type: array items: type: string - name: siteId in: query description: 'The UUID of the site. (Ex. `flooruuid`) Examples: `?siteId=id1` (single id requested) `?siteId=id1&siteId=id2&siteId=id3` (multiple ids requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchy in: query description: 'The full hierarchical breakdown of the site tree starting from Global site name and ending with the specific site name. The Root site is named "Global" (Ex. `Global/AreaName/BuildingName/FloorName`) This field supports wildcard asterisk (`*`) character search support. E.g. `*/San*, */San, /San*` Examples: `?siteHierarchy=Global/AreaName/BuildingName/FloorName` (single siteHierarchy requested) `?siteHierarchy=Global/AreaName/BuildingName/FloorName&siteHierarchy=Global/AreaName2/BuildingName2/FloorName2` (multiple siteHierarchies requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchyId in: query description: 'The full hierarchy breakdown of the site tree in id form starting from Global site UUID and ending with the specific site UUID. (Ex. `globalUuid/areaUuid/buildingUuid/floorUuid`) This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*` Examples: `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid `(single siteHierarchyId requested) `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid&siteHierarchyId=globalUuid/areaUuid2/buildingUuid2/floorUuid2` (multiple siteHierarchyIds requested) ' required: false style: form explode: true schema: type: array items: type: string - name: deviceCategory in: query description: "The list of device deviceCategories. \n\nExamples:\n\n`deviceCategory=AccessPoint` (single device family\ \ requested)\n\n`deviceCategory=AccessPoint&deviceCategory=OtherPOEDevice` (multiple device categories with comma\ \ separator)\n" required: false style: form explode: true schema: type: array items: type: string format: string enum: - AccessPoint - WirelessController - Sensor - OtherPOEDevice - name: deviceSubCategory in: query description: 'The list of device sub categories. Examples: `deviceSubCategory=IP Phone 7821` (single sub category requested) `deviceSubCategory=IP Phone 7821&deviceSubCategory=IEEE PD` ' required: false style: form explode: true schema: type: array items: type: string format: string - name: view in: query description: 'List of views. View and attribute work in union. Each view will include its attributes. For example, view device includes all the attributes related to device. Please refer to `ClientDeviceEnergyView` model for supported list of views Examples: `view=device&view=energy` ' required: false style: form explode: true schema: type: array items: type: string - name: attribute in: query description: "List of attributes. Please refer to `ClientDeviceEnergyAttribute` for supported list of attributes \ \ \n\nExamples:\n`attribute=id&attribute=energyConsumed`\n" required: false style: form explode: true schema: type: array items: type: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent responses: '200': description: Devices Energy Summaries Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ClientDevicesEnergyResponse' example: response: - id: 00:7E:95:79:99:17 deviceName: SEP007E95799917 connectedDeviceName: ott-sda-c9k-21.cisco.com connectedInterfaceName: GigabitEthernet1/1/0 deviceCategory: OtherPOEDevice deviceSubCategory: IP Phone 7821 siteId: 8f741bdf-788c-48f7-8ab1-017a826e4521 siteHierarchy: Global/Country1/Site1 siteHierarchyId: 8f741bdf-788c-48f7-8ab1-017a826e4521/8f741bdf-788c-48f7-8ab1-017a826e4521 energyConsumed: 2023 estimatedCost: 2524.23 estimatedEmission: 513 carbonIntensity: 123 page: limit: 10 cursor: eyJ1dWlkX3Rlcm1zIjoiZTBlM2VkMDgtNjE5OS00ZmVmLWFiNDEtZjA4OTcwMTMzYjdkIn0= count: 20 sortBy: - name: name order: asc version: '2.0' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/networkDevices/{id}: get: tags: - energy summary: Get device energy by ID description: Retrieves network device energy data for a specified time range based on the device ID. Returns the latest available snapshot of energy data between the provided start and end times. If no start and end times are specified, it defaults to returning the latest available energy data for the past 24 hours. operationId: readNetworkDevicesEnergyById parameters: - name: id in: path description: The UUID of the Network Device. (Ex. "6bef213c-19ca-4170-8375-b694e251101c") required: true style: simple explode: false schema: type: string - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: view in: query description: 'List of views. View and attribute work in union. Each view will include its attributes. For example, view device includes all the attributes related to device. Please refer to `NetworkDeviceEnergyView` model for supported list of views Examples: `view=device&view=energy` ' required: false style: form explode: true schema: type: array items: type: string - name: attribute in: query description: "List of attributes. Please refer to `NetworkDeviceEnergyAttribute` for supported list of attributes\ \ \n\nExamples:\n`attribute=id&attribute=energyConsumed`\n" required: false style: form explode: true schema: type: array items: type: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent responses: '200': description: Device Energy Summaries Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/NetworkDeviceEnergyResponse' example: response: id: 8f741bdf-788c-48f7-8ab1-017a826e4521 deviceName: sda-c9k-100.cisco.com deviceCategory: Switches deviceSubCategory: Cisco Catalyst 9300 Series Switches siteId: 8f741bdf-788c-48f7-8ab1-017a826e4521 siteHierarchy: Global/Country1/Site1 siteHierarchyId: 8f741bdf-788c-48f7-8ab1-017a826e4521/8f741bdf-788c-48f7-8ab1-017a826e4521 energyConsumed: 2023 estimatedCost: 2524.23 estimatedEmission: 513 carbonIntensity: 123 version: '2.0' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The client made a request for a resource that does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/clients/{id}: get: tags: - energy summary: Get client energy by ID description: Retrieves client device energy data for a specified time range based on the client ID. Returns the latest available snapshot of energy data between the provided start and end times. If no start and end times are specified, it defaults to returning the latest available energy data for the past 24 hours. operationId: readClientDevicesEnergyById parameters: - name: id in: path description: "Mac address of a client device (e.g., 54:9F:C6:43:FF:80). It can be specified is any notational conventions\ \ \n 01:23:45:67:89:AB or 01-23-45-67-89-AB or 0123.4567.89AB and is case insensitive." required: true style: simple explode: false schema: pattern: ^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$|^[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}\.[0-9A-Fa-f]{4}$ type: string - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: view in: query description: 'List of views. View and attribute work in union. Each view will include its attributes. For example, view device includes all the attributes related to device. Please refer to `ClientDeviceEnergyView` model for supported list of views Examples: `view=device&view=energy` ' required: false style: form explode: true schema: type: array items: type: string - name: attribute in: query description: "List of attributes. Please refer to `ClientDeviceEnergyAttribute` for supported list of attributes \ \ \n\nExamples:\n`attribute=id&attribute=energyConsumed`\n" required: false style: form explode: true schema: type: array items: type: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent responses: '200': description: Device Energy Summaries Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ClientDeviceEnergyResponse' example: response: id: 54:9F:C6:43:FF:80 deviceName: SEPAC7E8AB6B5D6 connectedDeviceName: ott-sda-c9k-575 connectedInterfaceName: GigabitEthernet1/1/0 deviceCategory: OtherPOEDevice deviceSubCategory: IP Phone 8865 siteId: 8f741bdf-788c-48f7-8ab1-017a826e4521 siteHierarchy: Global/Country1/Site1 siteHierarchyId: 8f741bdf-788c-48f7-8ab1-017a826e4521/8f741bdf-788c-48f7-8ab1-017a826e4521 energyConsumed: 2023 estimatedCost: 2524.23 estimatedEmission: 513 carbonIntensity: 123 version: '2.0' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The client made a request for a resource that does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/networkDevices/count: get: tags: - energy summary: Count devices energy description: Retrieves the total count of network devices that provide energy data, filtered according to the specified query parameters. operationId: countNetworkDevicesEnergy parameters: - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: id in: query description: 'The list of Device Uuids (e.g., `6bef213c-19ca-4170-8375-b694e251101c`). Examples: `id=6bef213c-19ca-4170-8375-b694e251101c` (single device requested) `id=6bef213c-19ca-4170-8375-b694e251101c&id=32219612-819e-4b5e-a96b-cf22aca13dd9` ' required: false style: form explode: true schema: type: array items: type: string - name: siteId in: query description: 'The UUID of the site. (Ex. `flooruuid`) Examples: `?siteId=id1` (single id requested) `?siteId=id1&siteId=id2&siteId=id3` (multiple ids requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchy in: query description: 'The full hierarchical breakdown of the site tree starting from Global site name and ending with the specific site name. The Root site is named "Global" (Ex. `Global/AreaName/BuildingName/FloorName`) This field supports wildcard asterisk (`*`) character search support. E.g. `*/San*, */San, /San*` Examples: `?siteHierarchy=Global/AreaName/BuildingName/FloorName` (single siteHierarchy requested) `?siteHierarchy=Global/AreaName/BuildingName/FloorName&siteHierarchy=Global/AreaName2/BuildingName2/FloorName2` (multiple siteHierarchies requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchyId in: query description: 'The full hierarchy breakdown of the site tree in id form starting from Global site UUID and ending with the specific site UUID. (Ex. `globalUuid/areaUuid/buildingUuid/floorUuid`) This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*` Examples: `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid `(single siteHierarchyId requested) `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid&siteHierarchyId=globalUuid/areaUuid2/buildingUuid2/floorUuid2` (multiple siteHierarchyIds requested) ' required: false style: form explode: true schema: type: array items: type: string - name: deviceCategory in: query description: "The list of device deviceCategories. \n\nExamples:\n\n`deviceCategory=Switch` (single device family\ \ requested)\n\n`deviceCategory=Switch&deviceCategory=Router` (multiple device categories with comma separator)\n" required: false style: form explode: true schema: type: array items: type: string format: string enum: - Switch - Router - name: deviceSubCategory in: query description: 'The list of device sub categories. Examples: `deviceSubCategory=Cisco Catalyst 9300 Series Switches` (single device family requested) `deviceSubCategory=Cisco Catalyst 9300 Series Switches&deviceSubCategory=Cisco Catalyst 9400 Series Switches` ' required: false style: form explode: true schema: type: array items: type: string format: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent responses: '200': description: Reponse object containing total count of the records after applying requested filters content: application/json: schema: $ref: '#/components/schemas/CountIntegerResponse' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/clients/count: get: tags: - energy summary: Count clients energy description: Retrieves the total count of client devices that provide energy data, filtered according to the specified query parameters. operationId: countClientDevicesEnergy parameters: - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: id in: query description: 'The list of Mac addresses (e.g., `54:9F:C6:43:FF:80`). Examples: `id=54:9F:C6:43:FF:80` (single device requested) `id=54:9F:C6:43:FF:80&id=01:23:45:67:89:AB` ' required: false style: form explode: true schema: type: array items: type: string - name: siteId in: query description: 'The UUID of the site. (Ex. `flooruuid`) Examples: `?siteId=id1` (single id requested) `?siteId=id1&siteId=id2&siteId=id3` (multiple ids requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchy in: query description: 'The full hierarchical breakdown of the site tree starting from Global site name and ending with the specific site name. The Root site is named "Global" (Ex. `Global/AreaName/BuildingName/FloorName`) This field supports wildcard asterisk (`*`) character search support. E.g. `*/San*, */San, /San*` Examples: `?siteHierarchy=Global/AreaName/BuildingName/FloorName` (single siteHierarchy requested) `?siteHierarchy=Global/AreaName/BuildingName/FloorName&siteHierarchy=Global/AreaName2/BuildingName2/FloorName2` (multiple siteHierarchies requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchyId in: query description: 'The full hierarchy breakdown of the site tree in id form starting from Global site UUID and ending with the specific site UUID. (Ex. `globalUuid/areaUuid/buildingUuid/floorUuid`) This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*` Examples: `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid `(single siteHierarchyId requested) `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid&siteHierarchyId=globalUuid/areaUuid2/buildingUuid2/floorUuid2` (multiple siteHierarchyIds requested) ' required: false style: form explode: true schema: type: array items: type: string - name: deviceCategory in: query description: "The list of device deviceCategories. \n\nExamples:\n\n`deviceCategory=AccessPoint` (single device family\ \ requested)\n\n`deviceCategory=AccessPoint&deviceCategory=OtherPOEDevice` (multiple device categories with comma\ \ separator)\n" required: false style: form explode: true schema: type: array items: type: string format: string enum: - AccessPoint - WirelessController - Sensor - OtherPOEDevice - name: deviceSubCategory in: query description: 'The list of device sub categories. Examples: `deviceSubCategory=IP Phone 7821` (single sub category requested) `deviceSubCategory=IP Phone 7821&deviceSubCategory=IEEE PD` ' required: false style: form explode: true schema: type: array items: type: string format: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent responses: '200': description: Reponse object containing total count of the records after applying requested filters content: application/json: schema: $ref: '#/components/schemas/CountIntegerResponse' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/networkDevices/query: post: tags: - energy summary: Query devices energy. description: "Retrieves a list of network devices along with their energy data for a specified time range, based on\ \ the filters provided in the request body.\n\n**The input payload contains the following fields**\n|Field Name |\ \ Description |\n| --- | --- |\n| `startTime` | Start time from which API queries the data set related to the resource.\ \ It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API\ \ will default to one day before `endTime`. |\n| `endTime` | End time to which API queries the data set related to\ \ the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided,\ \ API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current\ \ time. |\n| `attributes` | An optional filed that is used to get certain attributes in the response. The supported\ \ attributes are listed in `networkDeviceEnergyAttributes` model. Note: When view and attributes have different variants,\ \ the attributes returned in the response will be the union of both sets. |\n| `views` | An optional field, similar\ \ to attributes, is useful when a large number of fields are required in the response data. The supported logical\ \ views and their respective fields are available in `networkDeviceEnergyViews`. |\n| `filters` | Used to define\ \ one or more filter conditions. Only devices that satisfy these conditions will be taken into consideration during\ \ the aggregation calculation. This field can be empty. The supported list of filter keys and operators are: **\"\ id\" - [eq, in], \"deviceName\" - [eq, in, like], \"deviceCategory\" - [eq, in], \"deviceSubCategory\" - [eq, in],\ \ \"siteId\" - [eq, in], \"siteHierarchy\"-[eq, in, like], \"siteHierarchyId\" - [eq, in, like]**.\n| `aggregateAttributes`\ \ | Specifies the name of the attribute on which the aggregate function should be applied when querying the data.\ \ The supported attribute names are listed in `DevicesEnergyAggregateAttribute` model. | \n|`page`| Contains\ \ **limit, cursor and sortBy** fields. *limit* - Number of records to fetch in a page, *cursor* - string field indicating\ \ the next record in the response list and *sortBy* - attribute name, order and function if you want to sort by the\ \ aggregated field. *sortBy* field is a list, but only single field sorting is supported on this API.|\n\n**How the\ \ filtering behavior works**\n\nThe filters field in each post body can be used in numerous ways:\n\nEach filter in\ \ the list of filters will applied ''together''\n\nIn the example below, this would request filtering data from devices\ \ belonging to the ''Switch'' family `and` have series equal to ''cat9300'' or ''cat9400'.\n```\n\"filters\": [\n\ \ {\n \"key\": \"deviceCategory\",\n \"operator\": \"eq\",\n \"value\": \"Switch\"\n },\n \ \ {\n \"key\": \"deviceSubCategory\",\n \"operator\": \"in\",\n \"value\": [\"cat9300\", \"cat9400\"\ ]\n }\n]\n```\n\nEach filter object can contrastingly utilize its `logical operator` to provide nested filtering\ \ functionality.\n\nIn the example below you can see a logical \"OR\" filter being applied using the nested filtering\ \ functionality:\n\nThe primary filter object does not have its 'key', 'value', or 'operator' fields populated. Only\ \ the 'logicalOperator' field is populated, to indicate the filters within the nested filters list are to be logically\ \ conjoined.\n\n```\n\"filters\": [\n {\n \"logicalOperator\": \"or\",\n \"filters\": [\n {\n\ \ \"key\": \"deviceCategory\",\n \"operator\": \"eq\",\n \"value\": \"Switch\"\n \ \ },\n {\n \"key\": \"deviceSubCategory\",\n \"operator\": \"in\",\n \"value\"\ : [\"cat9300\", \"cat9400\"]\n }\n ]\n }\n]\n```\nPlease refer to the 'API Support Documentation' section\ \ to understand which fields and filters are supported.\n\n**How Pagination Works**\n\n'limit' field, is the total\ \ number of records you want to retrieve.\n\n'cursor' field, indicating the next record in the response list.\n\n\ If you have a limit of 100, each page would be viewed as 100 elements. So starting with an empty cursor, means look\ \ at the first page (starting from first record). To get the second page, you need to specify cursor returned in the\ \ response of the first request.\n\n'sortBy' field is a list, but only single field sorting is supported on this API.\n\ \nwith 'asc' (ascending), or 'desc' (descending) ordering\n\n**Example 1**\n\nRequest body\n\n```\n{\n \"startTime\"\ : 1703195600000,\n \"endTime\": 1707800400000,\n \"filters\": [\n {\n \"key\": \"id\",\n \ \ \"operator\": \"in\",\n \"value\": [\"f4b8bceb-588b-490c-b726-3dd8caf65071\"]\n }\n\ \ ],\n \"views\": [\"device\"],\n \"attributes\": [\"siteHierarchy\"],\n \"page\": {\n \"limit\"\ : 100,\n \"cursor\": \"\"\n }\n}\n```\n\nResponse:\n\n``` {\n \"response\": [\n {\n \ \ \"id\": \"f4b8bceb-588b-490c-b726-3dd8caf65071\",\n \"deviceName\": \"ott-sda-c9k-01.cisco.com\"\ ,\n \"deviceCategory\": \"Switch\",\n \"deviceSubCategory\": \"Cisco Catalyst 9300 Switch\"\ ,\n \"siteHierarchy\": \"Global/Ottawa\"\n }\n ],\n \"page\": {\n \ \ \"limit\": 100,\n \"cursor\": \"abcd123\",\n \"count\": 1,\n \"sortBy\": null\n\ \ },\n \"version\": \"1.0\"\n }\n```\n" operationId: queryNetworkDevicesEnergy parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent requestBody: description: Payload to query device energy summaries content: application/json: schema: $ref: '#/components/schemas/NetworkDeviceEnergyQueryRequest' examples: WithViewPassedQueryAPIRequestExample: $ref: '#/components/examples/QueryWithViewPassedRequestExample' WithoutViewPassedQueryAPIRequestExample: $ref: '#/components/examples/QueryWithoutViewPassedRequestExample' required: true responses: '200': description: Devices Energy Summaries Query Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/NetworkDevicesEnergyQueryResponse' examples: WithViewPassedQueryResponseExample: $ref: '#/components/examples/QueryWithViewPassedResponseExample' WithoutViewPassedQueryAPIResponseExample: $ref: '#/components/examples/QueryWithoutViewPassedResponseExample' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/clients/query: post: tags: - energy summary: Query clients energy description: "Retrieves a list of client devices along with their energy data for a specified time range, based on the\ \ filters provided in the request body.\n\n**The input payload contains the following fields**\n|Field Name | Description\ \ |\n| --- | --- |\n| `startTime` | Start time from which API queries the data set related to the resource. It must\ \ be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default\ \ to one day before `endTime`. |\n| `endTime` | End time to which API queries the data set related to the resource.\ \ It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will\ \ default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. |\n\ | `attributes` | An optional filed that is used to get certain attributes in the response. The supported attributes\ \ are listed in `clientDeviceEnergyAttributes` model. Note: When view and attributes have different variants, the\ \ attributes returned in the response will be the union of both sets. |\n| `views` | An optional field, similar to\ \ attributes, is useful when a large number of fields are required in the response data. The supported logical views\ \ and their respective fields are available in `clientDeviceEnergyViews` |\n| `filters` | Used to define one or more\ \ filter conditions. Only devices that satisfy these conditions will be taken into consideration during the aggregation\ \ calculation. This field can be empty. The supported list of filter keys and operators are: **\"siteId\" - [\"eq\"\ , \"in\"],\"siteHierarchy\"-[\"in\", \"eq\", \"like\"], \"siteHierarchyId\" - [\"in\", \"eq\", \"like\"], \"deviceCategory\"\ \ - [in, eq], \"deviceSubCategory\" - [in, eq], \"Id\" - [in, eq]**.\n| `aggregateAttributes` | specifies the name\ \ of the attribute on which the aggregate function should be applied when querying the data. The supported attribute\ \ names are listed in `DevicesEnergyAggregateAttribute` model. Supported functions today are just `sum` | \ \ \n|`page`| Contains **limit, cursor and sortBy** fields. *limit* - Number of records to fetch in a page, *cursor*\ \ - string field indicating the next record in the response list and *sortBy* - attribute name, order and function\ \ if you want to sort by the aggregated field. *sortBy* field is a list, but only single field sorting is supported\ \ on this API.|\n\nPlease refer to the 'API Support Documentation' section to understand which fields and filters\ \ are supported.\n\n**How Pagination Works**\n\n'limit' field, is the total number of records you want to retrieve.\n\ \n'cursor' field, indicating the next record in the response list.\n\nIf you have a limit of 100, each page would\ \ be viewed as 100 elements. So starting with an empty cursor, means look at the first page (starting from first record).\ \ To get the second page, you need to specify cursor returned in the response of the first request.\n\n'sortBy' field\ \ is a list, but only single field sorting is supported on this API.\n\nwith 'asc' (ascending), or 'desc' (descending)\ \ ordering\n" operationId: queryClientDevicesEnergy parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent requestBody: description: Payload to query device energy summaries content: application/json: schema: $ref: '#/components/schemas/ClientDeviceEnergyQueryRequest' examples: WithViewPassedQueryAPIRequestExample: $ref: '#/components/examples/QueryWithViewPassedRequestExample' WithoutViewPassedQueryAPIRequestExample: $ref: '#/components/examples/QueryWithoutViewPassedRequestExample' required: true responses: '200': description: Devices Energy Summaries Query Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/ClientDevicesEnergyQueryResponse' examples: WithoutViewPassedQueryAPIResponseExample: $ref: '#/components/examples/ClientDeviceQueryWithoutViewPassedResponseExample' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/networkDevices/query/count: post: tags: - energy summary: Count devices energy from query description: Retrieves the total count of network devices based on the specified complex filters. The request payload format is similar to that used with the query API. operationId: queryNetworkDevicesEnergyCount parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent requestBody: description: Payload to query device energy summaries count content: application/json: schema: $ref: '#/components/schemas/NetworkDeviceEnergyQueryRequest' examples: WithViewPassedQueryAPIRequestExample: $ref: '#/components/examples/QueryWithViewPassedRequestExample' responses: '200': description: Reponse object containing total count of the records after applying requested filters content: application/json: schema: $ref: '#/components/schemas/CountIntegerResponse' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/clients/query/count: post: tags: - energy summary: Count clients energy from query description: Retrieves the total count of client devices based on the specified complex filters. The request payload format is similar to that used with the query API. operationId: queryClientDevicesEnergyCount parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent requestBody: description: Payload to query device energy summaries count content: application/json: schema: $ref: '#/components/schemas/ClientDeviceEnergyQueryRequest' examples: WithViewPassedQueryAPIRequestExample: $ref: '#/components/examples/QueryWithViewPassedRequestExample' responses: '200': description: Reponse object containing total count of the records after applying requested filters content: application/json: schema: $ref: '#/components/schemas/CountIntegerResponse' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/summaryAnalytics: post: tags: - energy summary: Get energy summary analytics description: "Retrieve the summary analytics data related to device energy consumption for all devices, including network\ \ devices and clients assigned to specific sites. Utilize advanced filters to query a specific subset of energy information.\n\ \n**The input payload contains the following fields**\n|Field Name | Description |\n| --- | --- |\n| `startTime` |\ \ Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in\ \ milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`.\ \ |\n| `endTime` | End time to which API queries the data set related to the resource. It must be specified in UNIX\ \ epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`.\ \ If `startTime` is not provided either, API will default to current time. |\n| `filters` | Used to define one or\ \ more filter conditions. Only devices that satisfy these conditions will be taken into consideration during the aggregation\ \ calculation. This field can be empty. The supported list of filter keys and operators are: **\"id\", \"deviceName\"\ , \"deviceCategory\", \"deviceSubCategory\", siteId\", \"siteHierarchy\", \"siteHierarchyId\"**. |\n| `groupBy` |\ \ Specifies the attributes for grouping the data. The supported attributes are speficied in `DeviceEnergyGroupBy`\ \ model. As of now, Group by supports the following combinations of attributes: **[\"deviceCategory\"], [\"deviceSubCategory\"\ ], and [\"deviceCategory\", \"deviceSubCategory\"]**. |\n| `attributes` | The attribute is useful for obtaining one\ \ or more field data in addition to the aggregated data within the specified start and end time range. The supported\ \ attributes are listed in ` DeviceEnergyAttribute` model|\n| `aggregateAttributes` | Specifies the name of the attribute\ \ on which the aggregate function should be applied when querying the data. The supported attribute names are listed\ \ in `DevicesEnergyAggregateAttribute` model. |\n|`page`| Contains **limit, offset and sortBy** fields. *limit* -\ \ Number of records to fetch in a page, *offset* - starting offset of data and *sortBy* - attribute name, order and\ \ function if you want to sort by the aggregated field. *sortBy* field is a list, but only single field sorting is\ \ supported on this API.|\nNotes:\n * If \"groupby.attributes\" is left empty or set to default, the result will\ \ be an aggregation of all filtered data.\n * If no \"aggregateattributes\" are specified, the default attributes\ \ and functions appliedare \"avg\" for carbonIntensity and \"sum\" for \"energyConsumed\", \"estimatedCost\", and\ \ \"estimatedEmission\".\n\n**How the filtering behavior works**\n\nThe filters field in each post body can be used\ \ in numerous ways:\n\nEach filter in the list of filters will applied ''together''\n\nIn the example below, this\ \ would request filtering data from devices belonging to the ''Switch'' family `and` have series equal to ''cat9300''\ \ or ''cat9400'.\n```\n\"filters\": [\n {\n \"key\": \"deviceCategory\",\n \"operator\": \"eq\",\n \ \ \"value\": \"Switch\"\n },\n {\n \"key\": \"deviceSubCategory\",\n \"operator\": \"in\",\n \ \ \"value\": [\n \"cat9300\",\n \"cat9400\"\n ]\n }\n]\n```\n\nEach filter object can contrastingly\ \ utilize its `logical operator` to provide nested filtering functionality.\n\nIn the example below you can see a\ \ logical \"OR\" filter being applied using the nested filtering functionality:\n\nThe primary filter object does\ \ not have its 'key', 'value', or 'operator' fields populated. Only the 'logicalOperator' field is populated, to indicate\ \ the filters within the nested filters list are to be logically conjoined.\n\n```\n\"filters\": [\n {\n \"\ logicalOperator\": \"or\",\n \"filters\": [\n {\n \"key\": \"deviceCategory\",\n \"\ operator\": \"eq\",\n \"value\": \"Switch\"\n },\n {\n \"key\": \"deviceSubCategory\"\ ,\n \"operator\": \"in\",\n \"value\": [\"cat9300\", \"cat9400\"]\n }\n ]\n }\n]\n\ ```\nPlease refer to the 'API Support Documentation' section to understand which fields and filters are supported.\n\ \n**How Pagination Works**\n\n'limit' field, is the total number of records you want to retrieve.\n\n'offset' field,\ \ is the record you want to start on.\n\nIf you have a limit of 100, each page would be viewed as 100 elements. So\ \ starting with an offset of 1, means look at the first page (starting from first record). To get the second page,\ \ you need to specify offset 101 (starting with the 101st element). \n\n'sortBy' field is a list, but only single\ \ field sorting is supported on this API.\n\nwith 'asc' (ascending), or 'desc' (descending) ordering.\n\n\n \n\ \n\n```\n\n \"page\": {\n \"limit\": 5,\n \"offset\": 1,\n \"sortBy\": [\n {\n \"name\": \"\ siteId\",\n \"order\": \"desc\",\n \"function\": \"max\"\n }\n ]\n \n```\n\n**Example 1**:The\ \ JSON input below represents a request body used to retrieve sum data of deviceCount, energyConsumed on one specific\ \ site.\n \n\n```\n {\n \"startTime\": 1706590800000,\n \"endTime\": 1707496410913,\n \"filters\": [\n\ \ {\n \"key\": \"siteHierarchyId\",\n \"operator\": \"like\",\n \"value\"\ : \"/8df02c92-755e-4583-8c19-fb62ea75daf9/416e8ba7-87d6-43c4-943a-d33dd3a93236/006be1b2-ffea-4a0c-9783-1a845ccddfec*\"\ \n }\n ],\n \"aggregateAttributes\": [\n {\n \"name\": \"deviceCount\",\n \ \ \"function\": \"distinctCount\"\n },\n {\n \"name\": \"energyConsumed\",\n \ \ \"function\": \"sum\"\n }\n ],\n \"page\": {\n \"limit\": 100,\n \"offset\": 1\n \ \ }\n }\n \n```\n\n**Response**\n\n```\n {\n \"response\": {\n \"aggregateAttributes\": [\n \ \ {\n \"name\": \"deviceCount\",\n \"function\": \"distinctCount\",\n \ \ \"value\": 1\n },\n {\n \"name\": \"energyConsumed\",\n \"\ function\": \"sum\",\n \"value\": 108457.0\n }\n ]\n },\n \"page\": {\n \ \ \"limit\": 100,\n \"offset\": 1,\n \"count\": 1,\n \"sortBy\": null\n },\n \"version\"\ : \"1.0\"\n} ```\n" operationId: queryDeviceEnergySummaryAnalytics parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent requestBody: description: Payload to query summary analytics of device energy summaries content: application/json: schema: $ref: '#/components/schemas/DeviceEnergySummaryAnalyticsRequest' examples: GroupByRequestExample: $ref: '#/components/examples/SummaryAnalyticsWithGroupByRequestExample' WithoutGroupByRequestExample: $ref: '#/components/examples/SummaryAnalyticsWithoutGroupByRequestExample' required: true responses: '200': description: Devices Energy Summary Analytics Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/DeviceEnergySummaryAnalyticsResponse' examples: WithGroupByResponseExample: $ref: '#/components/examples/SummaryAnalyticsWithGroupByResponseExample' WithoutGroupByResponseExample: $ref: '#/components/examples/SummaryAnalyticsWithoutGroupByResponseExample' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /data/api/v1/energy/trendAnalytics: post: tags: - energy summary: Get energy trend analytics description: "Retrieve the energy trend analytics data related to device energy consumption for all devices, including\ \ network devices and clients assigned to specific sites. Utilize advanced filters to query a specific subset of energy\ \ information.\n\n**The input payload contains the following fields:**\n|Field Name | Description |\n| --- | --- |\n\ | `startTime` | Start time from which API queries the data set related to the resource. It must be specified in UNIX\ \ epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before\ \ `endTime`. |\n| `endTime` | End time to which API queries the data set related to the resource. It must be specified\ \ in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day\ \ after `startTime`. If `startTime` is not provided either, API will default to current time. |\n| `trendInterval`\ \ | Specifies the granularity on which data should be queried. Ex. If 1HR is specified than the data returned will\ \ in 1 hour interval. By default, if no value is specified - for 24 hours or less, it would be 1HR interval and anything\ \ more than 24 hours, the interval would be 1 day\n| `filters` | Used to define one or more filter conditions. Only\ \ devices that satisfy these conditions will be taken into consideration during the aggregation calculation. This\ \ field can be empty. The supported list of filter keys and operators are: **\"id\", \"deviceName\", \"deviceCategory\"\ , \"deviceSubCategory\", siteId\", \"siteHierarchy\", \"siteHierarchyId\"**. |\n| `groupBy` | Specifies the attributes\ \ for grouping the data. The supported attributes are speficied in `DeviceEnergyGroupBy` model. As of now, Group by\ \ supports the following combinations of attributes: **[\"deviceCategory\"], [\"deviceSubCategory\"], and [\"deviceCategory\"\ , \"deviceSubCategory\"]**. |\n| `attributes` | The attribute is useful for obtaining one or more field data in addition\ \ to the aggregated data within the specified start and end time range. The supported attributes are listed in ` DeviceEnergyAttribute`\ \ model|\n| `aggregateAttributes` | Specifies the name of the attribute on which the aggregate function should be\ \ applied when querying the data. The supported attribute names are listed in `DevicesEnergyAggregateAttribute` model.\ \ |\n|`page`| Contains **limit, offset and sortBy** fields. *limit* - Number of records to fetch in a page, *offset*\ \ - starting offset of data and *sortBy* - attribute name, order and function if you want to sort by the aggregated\ \ field. *sortBy* field is a list, but only single field sorting is supported on this API.|\nNotes:\n * If \"groupby.attributes\"\ \ is left empty or set to default, the result will be an aggregation of all filtered data.\n * If no \"aggregateattributes\"\ \ are specified, the default attributes and functions appliedare \"avg\" for carbonIntensity and \"sum\" for \"energyConsumed\"\ , \"estimatedCost\", and \"estimatedEmission\".\n\n**How the filtering behavior works**\n\nThe filters field in each\ \ post body can be used in numerous ways:\n\nEach filter in the list of filters will applied ''together''\n\nIn the\ \ example below, this would request filtering data from devices belonging to the ''Switch'' family `and` have series\ \ equal to ''cat9300'' or ''cat9400'.\n```\n\"filters\": [\n {\n \"key\": \"deviceCategory\",\n \"operator\"\ : \"eq\",\n \"value\": \"Switch\"\n },\n {\n \"key\": \"deviceSubCategory\",\n \"operator\":\ \ \"in\",\n \"value\": [\n \"cat9300\",\n \"cat9400\"\n ]\n }\n]\n```\n\nEach filter object\ \ can contrastingly utilize its `logical operator` to provide nested filtering functionality.\n\nIn the example below\ \ you can see a logical \"OR\" filter being applied using the nested filtering functionality:\n\nThe primary filter\ \ object does not have its 'key', 'value', or 'operator' fields populated. Only the 'logicalOperator' field is populated,\ \ to indicate the filters within the nested filters list are to be logically conjoined.\n\n```\n\"filters\": [\n \ \ {\n \"logicalOperator\": \"or\",\n \"filters\": [\n {\n \"key\": \"deviceCategory\"\ ,\n \"operator\": \"eq\",\n \"value\": \"Switch\"\n },\n {\n \"key\": \"\ deviceSubCategory\",\n \"operator\": \"in\",\n \"value\": [\"cat9300\", \"cat9400\"]\n }\n\ \ ]\n }\n]\n```\nPlease refer to the 'API Support Documentation' section to understand which fields and filters\ \ are supported.\n\n**How Pagination Works**\n\n'limit' field, is the total number of records you want to retrieve.\n\ \n'offset' field, is the record you want to start on.\n'timestampOrder' is supported for trend analytics with 'asc'\ \ (ascending), or 'desc' (descending) ordering\n\n\n**Example1** Request Body:\n\n```\n{\n \"startTime\": 1710964767403,\n\ \ \"endTime\": 1711051167403,\n \"filters\": [\n {\n \"key\": \"siteHierarchyId\",\n \ \ \"value\": \"/8df02c92-755e-4583-8c19-fb62ea75daf9*\",\n \"operator\": \"like\"\n }\n \ \ ],\n \"groupBy\": [],\n \"aggregateAttributes\": [\n {\n \"name\": \"energyConsumed\",\n\ \ \"function\": \n \"sum\"\n }\n ]\n ,\n \"page\": {\n \"limit\": 2,\n\ \ \"offset\": 1,\n \"timestampOrder\": \"desc\"\n } \n}\n```\nResponse: \n```\n{\n \"response\": [\n\ \ {\n \"time\": 1.7109648E+12,\n \"aggregateAttributes\": [\n {\n \ \ \"name\": \"energyConsumed\",\n \"function\": \"sum\",\n \"\ value\": 1343.875\n }\n ]\n \n },\n {\n \"time\": 1.7109684E+12,\n\ \ \"aggregateAttributes\": [\n {\n \"name\": \"energyConsumed\",\n \ \ \"function\": \"sum\",\n \"value\": 1033.25\n }\n \ \ ]\n }\n ],\n \"page\": {\n \"limit\": 2,\n \"offset\": 1,\n \"count\": 24,\n \ \ \"page\": {\n \"limit\": 2,\n \"offset\": 1,\n \"timestampOrder\": \"desc\"\n \ \ } \n }},\n \"version\": \"1.0\"\n}\n```\n" operationId: queryDeviceEnergyTrendAnalytics parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent requestBody: description: Payload to query trend analytics of device energy summaries content: application/json: schema: $ref: '#/components/schemas/DeviceEnergyTrendAnalyticsRequest' examples: RequestWithoutGroupByExample: $ref: '#/components/examples/TrendAnalyticsWithoutGroupByRequestExample' RequestWithGroupByExample: $ref: '#/components/examples/TrendAnalyticsWithGroupByRequestExample' required: true responses: '200': description: Devices Energy Trend Analytics Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/DeviceEnergyTrendAnalyticsResponse' examples: TrendAnalyticsWithGroupByResponseExample: $ref: '#/components/examples/TrendAnalyticsWithGroupByResponseExample' TrendAnalyticsWithoutGroupByResponseExample: $ref: '#/components/examples/TrendAnalyticsWithoutGroupByResponseExample' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /dna/data/api/v1/energy/sites: get: tags: - energy summary: Get sites energy description: "Retrieves a list of sites with energy data based on the specified query parameters. The response includes\ \ the total energy data for the period between the provided start and end times. If the start and end times are not\ \ specified, the data for the last 24 hours is returned.\n\n This API is asynchronous, which means there are two\ \ main steps using it, one to generate the request task ID, and another to get the response data. This process is\ \ as follows.\n\n 1. Make request to API to generate intended sites energy data. The response will be a 202 HTTP\ \ code with information regarding the generated taskId for this submitted request and the URL to poll the status of\ \ this task (e.g., */dna/data/api/v1/assuranceTasks/bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\n \n 2. Once the status\ \ is completed, the response data will be retrievable using the method GET of the same sites energy API endpoint by\ \ providing the query parameter `taskId` (e.g., */dna/data/api/v1/energy/sites?taskId=bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\ \ When a *taskId* is provided, all others query parameters are ignored." operationId: readSitesEnergy parameters: - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: limit in: query description: Maximum number of records to return schema: minimum: 1 type: integer default: 500 - name: offset in: query description: Specifies the starting point within all records returned by the API. It's one based offset. The starting value is 1. schema: minimum: 1 type: integer default: 1 - name: sortBy in: query description: A field within the response to sort by. schema: type: string - name: order in: query description: The sort order of the field ascending or descending. schema: type: string default: asc enum: - asc - desc - name: siteHierarchy in: query description: 'The full hierarchical breakdown of the site tree starting from Global site name and ending with the specific site name. The Root site is named "Global" (Ex. `Global/AreaName/BuildingName/FloorName`) This field supports wildcard asterisk (`*`) character search support. E.g. `*/San*, */San, /San*` Examples: `?siteHierarchy=Global/AreaName/BuildingName/FloorName` (single siteHierarchy requested) `?siteHierarchy=Global/AreaName/BuildingName/FloorName&siteHierarchy=Global/AreaName2/BuildingName2/FloorName2` (multiple siteHierarchies requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchyId in: query description: 'The full hierarchy breakdown of the site tree in id form starting from Global site UUID and ending with the specific site UUID. (Ex. `globalUuid/areaUuid/buildingUuid/floorUuid`) This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*` Examples: `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid `(single siteHierarchyId requested) `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid&siteHierarchyId=globalUuid/areaUuid2/buildingUuid2/floorUuid2` (multiple siteHierarchyIds requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteName in: query description: 'The name of the site. (Ex. `FloorName`) This field supports wildcard asterisk (`*`) character search support. E.g. `*San*, *San, San*` Examples: `?siteName=building1` (single siteName requested) `?siteName=building1&siteName=building2&siteName=building3` (multiple siteNames requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteType in: query description: 'The type of the site. A site can be an area, building, or floor. Default when not provided will be `[floor,building,area]` Examples: `?siteType=area` (single siteType requested) `?siteType=area&siteType=building&siteType=floor` (multiple siteTypes requested) ' required: false style: form explode: true schema: type: array items: type: string default: floor,building,area - name: deviceCategory in: query description: "The list of device categories. Note that this filter specifies which devices will be included when calculating\ \ energy consumption values, rather than specifying the list of returned sites. \n\nExamples:\n\n`deviceCategory=Switch`\ \ (single device category requested)\n\n`deviceCategory=Switch&deviceCategory=Router` (multiple device categories\ \ with comma separator)\n" required: false style: form explode: true schema: type: array items: type: string format: string - name: siteId in: query description: 'The UUID of the site. (Ex. `flooruuid`) Examples: `?siteId=id1` (single id requested) `?siteId=id1&siteId=id2&siteId=id3` (multiple ids requested) ' required: false style: form explode: true schema: type: array items: type: string - name: views in: query description: "The specific summary view being requested. This is an optional parameter which can be passed to get\ \ one or more of the specific health data summaries associated with sites.\n\n### Response data proviced by each\ \ view: \n\n1. **Site**\n[id, siteHierarchy, siteHierarchyId, siteType, latitude, longitude] \n\n2. **Energy**\n\ [energyConsumed, estimatedCost, estimatedEmission, carbonIntensity, numberOfDevices] \n\nWhen this query parameter\ \ is not added the default summaries are: \n\n**[site,energy]**\n\nExamples:\n\nviews=site (single view requested)\n\ \nviews=site,energy (multiple views requested)\n" required: false style: form explode: true schema: maxItems: 5 minItems: 1 type: array items: type: string default: - site - energy - name: attribute in: query description: 'Supported Attributes: [id, siteHierarchy, siteHierarchyId, siteType, latitude, longitude, energyConsumed, estimatedCost, estimatedEmission, carbonIntensity, numberOfDevices] If length of attribute list is too long, please use ''view'' param instead. Examples: attribute=siteHierarchy (single attribute requested) attribute=siteHierarchy&attribute=energyConsumed (multiple attributes requested) ' required: false style: form explode: true schema: maxItems: 5 minItems: 1 type: array items: type: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent - name: taskId in: query description: 'used to retrieve asynchronously processed & stored data. When this parameter is used, the rest of the request params will be ignored. ' schema: type: string responses: '200': description: Site Energy Summaries Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/SitesEnergyResponse' example: response: - id: dc55b6c0-fc6f-4362-8078-9487c6d1119d siteHierarchy: Global/Canada/Ottawa/2000 innovation siteHierarchyId: /9722c7e7-90c5-4af0-a77b-fa007f391f64/bba8d2b8-f3cb-45bd-9a0c-ded436246e0e/1cc17af5-387f-4fa9-82f9-b74bdc24df6b/dc55b6c0-fc6f-4362-8078-9487c6d1119d/ siteType: building latitude: 45.342065 longitude: -75.926259 deviceCategories: - Switch - AccessPoint numberOfDevices: 2 parentSiteId: 1cc17af5-387f-4fa9-82f9-b74bdc24df6b energyConsumed: 191697 estimatedCost: 798 estimatedEmission: 653.3 carbonIntensity: 227.864 - id: 1cc17af5-387f-4fa9-82f9-b74bdc24df6b siteHierarchy: Global/Canada/Ottawa siteHierarchyId: /9722c7e7-90c5-4af0-a77b-fa007f391f64/bba8d2b8-f3cb-45bd-9a0c-ded436246e0e/1cc17af5-387f-4fa9-82f9-b74bdc24df6b/ siteType: area deviceCategories: - Switch - AccessPoint - OtherPOEDevices numberOfDevices: 3 parentSiteId: bba8d2b8-f3cb-45bd-9a0c-ded436246e0e energyConsumed: 191697 estimatedCost: 798 estimatedEmission: 653.3 carbonIntensity: 227.864 page: limit: 10 offset: 1 count: 20 sortBy: - name: name order: asc version: '1.0' '202': description: Response model for asynchronous APIs to use for providing corresponding task information to API caller content: application/json: schema: $ref: '#/components/schemas/asyncInfoContainer' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /dna/data/api/v1/energy/sites/{id}: get: tags: - energy summary: Get site energy by ID description: "Retrieve the energy summary data for a specific site based on the site ID.\n\n This API is asynchronous,\ \ which means there are two main steps using it, one to generate the request task ID, and another to get the response\ \ data. This process is as follows.\n\n 1. Make request to API to generate intended sites energy data. The response\ \ will be a 202 HTTP code with information regarding the generated taskId for this submitted request and the URL to\ \ poll the status of this task (e.g., */dna/data/api/v1/assuranceTasks/bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\n \ \ \n 2. Once the status is completed, the response data will be retrievable using the method GET of the same sites\ \ energy API endpoint by providing the query parameter `taskId` (e.g., */dna/data/api/v1/energy/sites/bcbb2a8c-deae-4a3e-9459-0eb1dc12c192?taskId=bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\ \ When a *taskId* is provided, all others query parameters are ignored." operationId: readSitesEnergyById parameters: - name: id in: path description: The UUID of the Site. (Ex. "6bef213c-19ca-4170-8375-b694e251101c") required: true style: simple explode: false schema: type: string - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: views in: query description: "The specific summary view being requested. This is an optional parameter which can be passed to get\ \ one or more of the specific health data summaries associated with sites.\n\n### Response data proviced by each\ \ view: \n\n1. **Site**\n[id, siteHierarchy, siteHierarchyId, siteType, latitude, longitude] \n\n2. **Energy**\n\ [energyConsumed, estimatedCost, estimatedEmission, carbonIntensity, numberOfDevices] \n\nWhen this query parameter\ \ is not added the default summaries are: \n\n**[site,energy]**\n\nExamples:\n\nviews=site (single view requested)\n\ \nviews=site,energy (multiple views requested)\n" required: false style: form explode: true schema: maxItems: 5 minItems: 1 type: array items: type: string default: - site - energy - name: attribute in: query description: 'Supported Attributes: [id, siteHierarchy, siteHierarchyId, siteType, latitude, longitude, energyConsumed, estimatedCost, estimatedEmission, carbonIntensity, numberOfDevices] If length of attribute list is too long, please use ''view'' param instead. Examples: attribute=siteHierarchy (single attribute requested) attribute=siteHierarchy&attribute=energyConsumed (multiple attributes requested) ' required: false style: form explode: true schema: maxItems: 5 minItems: 1 type: array items: type: string - name: deviceCategory in: query description: "The list of device categories. Note that this filter specifies which devices will be included when calculating\ \ energy consumption values, rather than specifying the list of returned sites. \n\nExamples:\n\n`deviceCategory=Switch`\ \ (single device category requested)\n\n`deviceCategory=Switch&deviceCategory=Router` (multiple device categories\ \ with comma separator)\n" required: false style: form explode: true schema: type: array items: type: string format: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent - name: taskId in: query description: 'used to retrieve asynchronously processed & stored data. When this parameter is used, the rest of the request params will be ignored. ' schema: type: string responses: '200': description: Site Energy Summaries Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/SiteEnergyResponse' example: response: id: dc55b6c0-fc6f-4362-8078-9487c6d1119d siteHierarchy: Global/Canada/Ottawa/2000 innovation siteHierarchyId: /9722c7e7-90c5-4af0-a77b-fa007f391f64/bba8d2b8-f3cb-45bd-9a0c-ded436246e0e/1cc17af5-387f-4fa9-82f9-b74bdc24df6b/dc55b6c0-fc6f-4362-8078-9487c6d1119d/ siteType: building latitude: 45.342065 longitude: -75.926259 deviceCategories: - Switch - AccessPoint - OtherPOEDevices numberOfDevices: 6 parentSiteId: 1cc17af5-387f-4fa9-82f9-b74bdc24df6b energyConsumed: 135423 estimatedCost: 724.5 estimatedEmission: 611.24 carbonIntensity: 44.508 '202': description: Response model for asynchronous APIs to use for providing corresponding task information to API caller content: application/json: schema: $ref: '#/components/schemas/asyncInfoContainer' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The client made a request for a resource that does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /dna/data/api/v1/energy/sites/count: get: tags: - energy summary: Count sites energy description: "Retrieves the total count of sites that provide energy data, filtered according to the specified query\ \ parameters.\n\n This API is asynchronous, which means there are two main steps using it, one to generate the request\ \ task ID, and another to get the response data. This process is as follows.\n\n 1. Make request to API to generate\ \ intended sites energy data. The response will be a 202 HTTP code with information regarding the generated taskId\ \ for this submitted request and the URL to poll the status of this task (e.g., */dna/data/api/v1/assuranceTasks/bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\n\ \ \n 2. Once the status is completed, the response data will be retrievable using the method GET of the same sites\ \ energy API endpoint by providing the query parameter `taskId` (e.g., */dna/data/api/v1/energy/sites/count?taskId=bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\ \ When a *taskId* is provided, all others query parameters are ignored." operationId: countSitesEnergy parameters: - name: startTime in: query description: 'Start time from which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime` is not provided, API will default to one day before `endTime`. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705348800000 - name: endTime in: query description: 'End time to which API queries the data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either, API will default to current time. ' required: false style: form explode: true schema: type: integer format: int64 example: 1705435200000 - name: siteHierarchy in: query description: 'The full hierarchical breakdown of the site tree starting from Global site name and ending with the specific site name. The Root site is named "Global" (Ex. `Global/AreaName/BuildingName/FloorName`) This field supports wildcard asterisk (`*`) character search support. E.g. `*/San*, */San, /San*` Examples: `?siteHierarchy=Global/AreaName/BuildingName/FloorName` (single siteHierarchy requested) `?siteHierarchy=Global/AreaName/BuildingName/FloorName&siteHierarchy=Global/AreaName2/BuildingName2/FloorName2` (multiple siteHierarchies requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteHierarchyId in: query description: 'The full hierarchy breakdown of the site tree in id form starting from Global site UUID and ending with the specific site UUID. (Ex. `globalUuid/areaUuid/buildingUuid/floorUuid`) This field supports wildcard asterisk (`*`) character search support. E.g. `*uuid*, *uuid, uuid*` Examples: `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid `(single siteHierarchyId requested) `?siteHierarchyId=globalUuid/areaUuid/buildingUuid/floorUuid&siteHierarchyId=globalUuid/areaUuid2/buildingUuid2/floorUuid2` (multiple siteHierarchyIds requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteName in: query description: 'The name of the site. (Ex. `FloorName`) This field supports wildcard asterisk (`*`) character search support. E.g. `*San*, *San, San*` Examples: `?siteName=building1` (single siteName requested) `?siteName=building1&siteName=building2&siteName=building3` (multiple siteNames requested) ' required: false style: form explode: true schema: type: array items: type: string - name: siteType in: query description: 'The type of the site. A site can be an area, building, or floor. Default when not provided will be `[floor,building,area]` Examples: `?siteType=area` (single siteType requested) `?siteType=area&siteType=building&siteType=floor` (multiple siteTypes requested) ' required: false style: form explode: true schema: type: array items: type: string default: floor,building,area - name: deviceCategory in: query description: "The list of device categories. Note that this filter specifies which devices will be included when calculating\ \ energy consumption values, rather than specifying the list of returned sites. \n\nExamples:\n\n`deviceCategory=Switch`\ \ (single device category requested)\n\n`deviceCategory=Switch&deviceCategory=Router` (multiple device categories\ \ with comma separator)\n" required: false style: form explode: true schema: type: array items: type: string format: string - name: siteId in: query description: 'The UUID of the site. (Ex. `flooruuid`) Examples: `?siteId=id1` (single id requested) `?siteId=id1&siteId=id2&siteId=id3` (multiple ids requested) ' required: false style: form explode: true schema: type: array items: type: string - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent - name: taskId in: query description: 'used to retrieve asynchronously processed & stored data. When this parameter is used, the rest of the request params will be ignored. ' schema: type: string responses: '200': description: Reponse object containing total count of the records after applying requested filters content: application/json: schema: $ref: '#/components/schemas/CountIntegerResponse' '202': description: Response model for asynchronous APIs to use for providing corresponding task information to API caller content: application/json: schema: $ref: '#/components/schemas/asyncInfoContainer' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /dna/data/api/v1/energy/sites/query: get: tags: - energy summary: Query sites energy for the given task ID description: 'Gets query sites energy task result for the given task ID. First use the POST API (POST /dna/data/api/v1/energy/sites/query) to submit a request to query sites energy, which returns a task ID. Then use this GET API and pass the taskId as query parameter to get the sites energy data. ' operationId: querySitesEnergyTask parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent - name: taskId in: query description: 'used to retrieve asynchronously processed & stored data. When this parameter is used, the rest of the request params will be ignored. ' schema: type: string responses: '200': description: Site Energy Summaries Query Response model on success content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/SitesEnergyQueryResponse' examples: SiteEnergyQueryAPIWithViewPassedResponseExample: $ref: '#/components/examples/SiteEnergyQueryAPIWithViewPassedResponseExample' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error post: tags: - energy summary: Submit request to query sites energy description: "Submits a request to retrieve a list of sites along with their energy data for a specified time range,\ \ based on the filters provided in the request body.\n\n This API is asynchronous, which means there are two main\ \ steps using it, one to generate the request task ID, and another to get the response data. This process is as follows.\n\ \n 1. Make request to API to generate intended sites energy data. The response will be a 202 HTTP code with information\ \ regarding the generated taskId for this submitted request and the URL to poll the status of this task (e.g., */dna/data/api/v1/assuranceTasks/bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\n\ \ \n 2. Once the status is completed, the response data will be retrievable using the method GET of the same sites\ \ energy API endpoint by providing the query parameter `taskId` (e.g., */dna/data/api/v1/energy/sites/query?taskId=bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\ \ When a *taskId* is provided, all others query parameters are ignored.\n\n**The input payload contains the following\ \ fields**\n|Field Name | Description |\n| --- | --- |\n| `startTime` | Start time from which API queries the data\ \ set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If `startTime`\ \ is not provided, API will default to one day before `endTime`. |\n| `endTime` | End time to which API queries the\ \ data set related to the resource. It must be specified in UNIX epochtime in milliseconds. Value is inclusive. If\ \ `endTime` is not provided, API will default to one day after `startTime`. If `startTime` is not provided either,\ \ API will default to current time. |\n| `views` | An optional field, similar to attributes, is useful when a large\ \ number of fields are required in the response data. The supported logical views and their respective fields are\ \ available in. Not specifying an option for \"view\" will return both energy and site fields. |\n| `attributes` |\ \ An optional filed that is used to get certain attributes in the response. The supported attributes are listed in\ \ `siteEnergyAttributes` model. Note: When view and attributes have different variants, the attributes returned in\ \ the response will be the union of both sets.\n| `filters` | Used to define one or more conditions. Only the devices\ \ that satisfy these conditions will be taken into consideration during the aggregation calculation. This field can\ \ be empty. The supported list of fiters are: **\"id\" - [eq, in], \"siteName\" - [eq, in, like], \"siteType\" - [eq,\ \ in], \"siteHierarchy\"-[eq, in, like], \"siteHierarchyId\" - [eq, in, like], and \"deviceCategory\" - [eq, in]**.\ \ Note that the \"devicecategory\" filter specifies which devices will be included when calculating energy consumption\ \ values, rather than specifying the list of returned sites.\n| `aggregateAttributes` | Specifies the name of the\ \ attribute on which the aggregate function should be applied when querying the data. The supported attribute names\ \ are listed in `SiteEnergyAggregateAttribute` model. |\n|`page`| contains **limit, offset and sortBy** fields. *limit*\ \ - Number of records to fetch in a page, *offset* - starting offset of data and *sortBy* - attribute name, order\ \ and function if you want to sort by the aggregated field. *sortBy* field is a list, but only single field sorting\ \ is supported on this API.|\n\n **How the filtering behavior works**\n\n\nThe filters field in each post body can\ \ be used in numerous ways:\n\nEach filter in the list of filters will applied ''together''.\n\nIn the example below,\ \ we would be filtering the sites to only include all the sites under \"/5b455edc-7c4e-4763-9bb3-5e826e20200f\". \n\ ```\n\"filters\": [\n {\n key: \"siteHierarchyId\",\n operator: \"like\",\n value: \"/5b455edc-7c4e-4763-9bb3-5e826e20200f.*\"\ \n }\n]\n```\n\nEach filter object can contrastingly utilize its `logical operator` to provide nested filtering functionality.\n\ Please refer to the 'API Support Documentation' section to understand which fields and filters are supported.\n\n\ **How Pagination Works**\n\n'limit' field, is the total number of records you want to retrieve.\n\n'offset' field,\ \ is the record you want to start on.\n\nIf you have a limit of 100, each page would be viewed as 100 elements. So\ \ starting with an offset of 1, means look at the first page (starting from first record). To get the second page,\ \ you need to specify offset 101 (starting with the 101st element). \n\n'sortBy' field is a list, but only single\ \ field sorting is supported on this API.\n\nwith 'asc' (ascending), or 'desc' (descending) ordering\n\n**Below is\ \ the sample example of the request payload.**\n```\n {\n \"startTime\": 1706590800000,\n \"endTime\": 1707496410913,\n\ \ \"filters\": [\n {\n \"key\": \"siteHierarchyId\",\n \"operator\": \"like\",\n \ \ \"value\": \"/8df02c92-755e-4583-8c19-fb62ea75daf9/416e8ba7-87d6-43c4-943a-d33dd3a93236/006be1b2-ffea-4a0c-9783-1a845ccddfec*\"\ \n }\n ],\n \"aggregateAttributes\": [\n {\n \"name\": \"deviceCount\",\n \ \ \"function\": \"distinctCount\"\n },\n {\n \"name\": \"energyConsumed\",\n \ \ \"function\": \"sum\"\n }\n ],\n \"page\": {\n \"limit\": 100,\n \"offset\": 1\n \ \ }\n }\n \n```\n" operationId: querySitesEnergy parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent requestBody: description: Post body to query a list of site energy summaries content: application/json: schema: $ref: '#/components/schemas/SitesEnergyQueryRequest' examples: SiteEnergyQueryAPIWithViewPassedRequestExample: $ref: '#/components/examples/SiteEnergyQueryAPIWithViewPassedRequestExample' required: true responses: '202': description: Response model for asynchronous APIs to use for providing corresponding task information to API caller content: application/json: schema: $ref: '#/components/schemas/asyncInfoContainer' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 /dna/data/api/v1/energy/sites/query/count: get: tags: - energy summary: Count sites energy for the given task ID description: 'Gets count sites energy task result for the given task ID. First use the POST API (POST /dna/data/api/v1/energy/sites/query/count) to submit a request to count sites energy, which returns a task ID. Then use this GET API and pass the taskId as query parameter to get the sites energy data. ' operationId: querySitesEnergyCountTask parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent - name: taskId in: query description: 'used to retrieve asynchronously processed & stored data. When this parameter is used, the rest of the request params will be ignored. ' schema: type: string responses: '200': description: Reponse object containing total count of the records after applying requested filters content: application/json: schema: $ref: '#/components/schemas/CountIntegerResponse' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error post: tags: - energy summary: Submit request to count sites energy from query description: "Submits a request to retrieve the total count of sites that provide energy data, filtered according to\ \ the specified query parameters. The request payload format is similar to that used with the query API.\n\n This\ \ API is asynchronous, which means there are two main steps using it, one to generate the request task ID, and another\ \ to get the response data. This process is as follows.\n\n 1. Make request to API to generate intended sites energy\ \ data. The response will be a 202 HTTP code with information regarding the generated taskId for this submitted request\ \ and the URL to poll the status of this task (e.g., */dna/data/api/v1/assuranceTasks/bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\n\ \ \n 2. Once the status is completed, the response data will be retrievable using the method GET of the same sites\ \ energy API endpoint by providing the query parameter `taskId` (e.g., */dna/data/api/v1/energy/sites/query/count?taskId=bcbb2a8c-deae-4a3e-9459-0eb1dc12c191*).\ \ When a *taskId* is provided, all others query parameters are ignored.\n" operationId: querySitesEnergyCount parameters: - name: X-CALLER-ID in: header description: 'Caller ID is used to trace the origin of API calls and their associated queries executed on the database. It''s an optional header parameter that can be added to an API request. ' required: false schema: type: string default: unknown example: intent requestBody: description: Payload to query site energy summaries count content: application/json: schema: $ref: '#/components/schemas/SitesEnergyQueryRequest' required: true responses: '202': description: Response model for asynchronous APIs to use for providing corresponding task information to API caller content: application/json: schema: $ref: '#/components/schemas/asyncInfoContainer' '400': description: The client made a request that the server could not understand (for example, the request syntax is incorrect). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: The server could not fulfill the request due to internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 1XX: description: Informational Responses - The server received the request and sent an informational response. 2XX: description: Successful Responses - The server received the client request, understood it, and accepted it. 3XX: description: Redirection Messages - The client must take additional action to complete the request. 4XX: description: Client Error Responses - The client request caused the error. 5XX: description: Server Error Responses - The server failed to fulfill the request. default: description: Unexpected Error servers: - url: https://developer.cisco.com/data/api/v1 components: schemas: ClientDeviceEnergy: type: object properties: id: type: string description: Mac address of the device. example: 54:9F:C6:43:FF:80 connectedDeviceName: type: string description: It is the switch name that the device is connected to. example: sda-c9k-100.cisco.com connectedInterfaceName: type: string description: Interface name. Will be empty in case of a switch. example: GigabitEthernet1/1/0 description: Assurance Client Device Energy Summaries details allOf: - $ref: '#/components/schemas/DeviceEnergy' startAndEndTime: type: object properties: startTime: type: integer description: 'Start time from which the API queries the dataset related to the resource. It must be specified in terms of milliseconds since UNIX epoch. Value is inclusive. If `startTime` is not provided, API will default to current time. ' format: int64 example: 1705348800000 endTime: type: integer description: 'End time to which the API queries the dataset related to the resource. It must be specified in terms of milliseconds since UNIX epoch. Value is inclusive. If `endTime` is not provided, API will default to current time. ' format: int64 example: 1705435200000 description: start and end time of data set to query. Data is aggregated based on time window and timestamped with window start time. | For example - 1. When data events falls in a 5 minute window from 12-13-2023 11:25 PM to 12-13-2023 11:30 PM the timestamp of the aggregated data is 12-13-2023 11:25 PM - 1702509900000 (Unix epochtime). If user needs data from 12-13-2023 11:25 PM to 12-13-2023 11:30 PM user must use below timestamps | startTime = 1702509900000 (12-13-2023 11:25 PM) | endTime = 1702510199000 (12-13-2023 11:29:59 PM) | 2. When data to be queried is for 3 hours period from 12-13-2023 08:30 PM to 12-13-2023 11:30 PM. User must use below timestamps | startTime = 1702528200000 (12-13-2023 08:30 PM) | endTime = 1702510199000 (12-13-2023 11:29:59 PM) | 2. When data to be queried is for 24 hours period from 12-12-2023 11:30 PM to 12-13-2023 11:30 PM. User must use below timestamps | startTime = 1702423800000 (12-12-2023 11:30 PM) | endTime = 1702510199000 (12-13-2023 11:29:59 PM) | 3. When data to be queried is for 7 days period from 12-06-2023 11:30 PM to 12-13-2023 11:30 PM. User must use below timestamps | startTime = 1701905400000 (12-06-2023 11:30 PM) | endTime = 1702510199000 (12-13-2023 11:29:59 PM) DeviceEnergyResponse_groups: type: object properties: id: type: string description: Unique ID of the Analytics response. The ID is the concatenation of all grouped attributes. attributes: $ref: '#/components/schemas/DeviceEnergyAttributesResponse' aggregateAttributes: $ref: '#/components/schemas/DeviceEnergyAggregateAttributesResponse' ClientDeviceEnergySortByObj: type: object properties: name: $ref: '#/components/schemas/ClientDeviceEnergyAttribute' order: type: string description: The sort order of the field ascending or descending. example: asc enum: - asc - desc function: $ref: '#/components/schemas/Function' description: 'This is a unified sortBy model for attributes and aggregate attributes request. If function is specified then API will sort the collection on aggregated attribute. If function is not specified API will sort the collection on attribute. ' NetworkDeviceEnergyFilters: type: array description: 'List of filters to apply when querying the device energy data. Supported operators are [in, eq, like] ' example: - key: deviceCategory operator: eq value: Switch - key: deviceSubCategory operator: in value: - Cisco Catalyst 9300 Switch - Cisco Catalyst 9400 Switch - logicalOperator: or filters: - key: deviceCategory operator: eq value: Switch - key: deviceSubCategory operator: in value: - Cisco Catalyst 9300 Switch - Cisco Catalyst 9400 Switch items: $ref: '#/components/schemas/NetworkDeviceEnergyFilter' NetworkDeviceEnergySortByObj: type: object properties: name: $ref: '#/components/schemas/NetworkDeviceEnergyAttribute' order: type: string description: The sort order of the field ascending or descending. example: asc enum: - asc - desc function: $ref: '#/components/schemas/Function' description: 'This is a unified sortBy model for attributes and aggregate attributes request. If function is specified then API will sort the collection on aggregated attribute. If function is not specified API will sort the collection on attribute. ' DeviceEnergyFilter: type: object properties: key: $ref: '#/components/schemas/DeviceEnergyFilterKey' operator: $ref: '#/components/schemas/Operator' logicalOperator: $ref: '#/components/schemas/LogicalOperator' value: type: object description: 'Field value(s) to filter the data set. Array of values is used for "in" or "out" operator. Values will be of whatever type the specific field being filtered is defined with. For other operators, filter value is of whatever type the specific field being filtered is defined with. In the case of an "and" or "or" operator, this values array will be ignored, and the values arrays in each of the *nested filters* will be used. ' filters: type: array description: 'Nested array of filters in case of AND/OR based filters. Only one level of nesting will be supported. Structure of nested filter is the same as parent with all operators supported except AND or OR. ' items: $ref: '#/components/schemas/DeviceEnergyFilter' description: 'In case of single filter, please use `key`, `operator` and `value` combination. If multiple filters need to be applied using a logical operation, please use `logicalOperator` and populate the list of ''filters'' with a combination of FilterObj. Filters can be nested to build complex queries. ' DeviceEnergyFilterKey: type: string description: Field names which are supported by this API for filter keys. enum: - id - deviceName - deviceCategory - deviceSubCategory - siteId - siteHierarchy - siteHierarchyId DeviceEnergyTrendInterval: type: string description: "The time window to aggregate the metrics. \nInterval can be 1 hour or 1 day.\n" example: 1HR default: 1HR enum: - 1HR - 1DAY ErrorObject: type: object properties: errorCode: type: integer description: Application specific error code returned by the server message: type: string description: Brief message about the error condition detail: type: string description: A more detailed explanation of the error condition the parameter and its value, that caused the condition and why it caused it. NetworkDevicesEnergyQueryResponse: type: object properties: response: type: array description: Successfully returned list of Devices Energy information items: allOf: - $ref: '#/components/schemas/NetworkDeviceEnergy' - type: object properties: aggregateAttributes: $ref: '#/components/schemas/DeviceEnergyAggregateAttributesResponse' description: Response object for device energy summaries query API. page: $ref: '#/components/schemas/NetworkDeviceEnergyPaginationWithAggregateSortBy' version: type: string description: The version of the response example: '2.0' NetworkDeviceEnergyView: type: string description: "Views which are supported by this API. Each view represents a specific data set.\n\n### Response data\ \ provided by each view: \n\n1. **device**\n[id, deviceId, deviceCategory, deviceSubCategory] \n\n2. **site**\n\ [id, siteId, siteHierarchy, siteHierarchyId] \n\n3. **energy**\n[id, energyConsumed, estimatedCost, estimatedEmission,\ \ carbonIntensity] \n\n4. **energyMix**\n[nuclearEnergyConsumed, geothermalEnergyConsumed,biomassEnergyConsumed,coalEnergyConsumed,\n\ \ windEnergyConsumed,solarEnergyConsumed,hydroEnergyConsumed\",gasEnergyConsumed,oilEnergyConsumed,unknownEnergyConsumed,hydroDischargeEnergyConsumed,batteryDischargeEnergyConsumed]\n\ When this list is not added the default summaries will be: \n\n**[device, site, energy]**\n" enum: - device - site - energy - energyMix - energySavings NetworkDeviceEnergyFilterKey: type: string description: Field names which are supported by this API for filter keys. enum: - id - deviceName - deviceCategory - deviceSubCategory - siteId - siteHierarchy - siteHierarchyId DeviceEnergySummaryAnalyticsRequest: type: object properties: filters: $ref: '#/components/schemas/DeviceEnergyFilters' attributes: type: array example: - deviceCategory - energyConsumed items: $ref: '#/components/schemas/DeviceEnergyAttribute' aggregateAttributes: type: array items: $ref: '#/components/schemas/DevicesEnergyAggregateAttribute' page: $ref: '#/components/schemas/DeviceEnergyPaginationWithAggregateSortBy' groupBy: $ref: '#/components/schemas/DeviceEnergyGroupBy' description: Request object for device summary analytics. allOf: - $ref: '#/components/schemas/startAndEndTime' ClientDeviceEnergyAttribute: type: string description: Field names which are supported by this API as attributes. enum: - id - deviceName - deviceCategory - deviceSubCategory - connectedDeviceName - connectedInterfaceName - siteId - siteHierarchy - siteHierarchyId - energyConsumed - estimatedCost - estimatedEmission - carbonIntensity - nuclearEnergyConsumed - geothermalEnergyConsumed - biomassEnergyConsumed - coalEnergyConsumed - windEnergyConsumed - solarEnergyConsumed - hydroEnergyConsumed - gasEnergyConsumed - oilEnergyConsumed - unknownEnergyConsumed - hydroDischargeEnergyConsumed - batteryDischargeEnergyConsumed - renewableEnergyConsumed - nonRenewableEnergyConsumed - fossilEnergyConsumed - fossilFreeEnergyConsumed - energySavings - costSavings - emissionSavings ClientDevicesEnergyQueryResponse: type: object properties: response: type: array description: Successfully returned list of Devices Energy information items: allOf: - $ref: '#/components/schemas/ClientDeviceEnergy' - type: object properties: aggregateAttributes: $ref: '#/components/schemas/DeviceEnergyAggregateAttributesResponse' description: Response object for device energy summaries query API. page: $ref: '#/components/schemas/ClientDeviceEnergyPaginationWithAggregateSortBy' version: type: string description: The version of the response example: '2.0' DeviceEnergy: type: object properties: deviceName: type: string description: Name of the device. example: sda-c9k-100.cisco.com deviceCategory: type: string description: Category of the device ex - Switch, OtherPOEdevice. example: Switch deviceSubCategory: type: string description: Sub category corresponds of the device. example: Cisco Catalyst 9300 Series Switches siteId: type: string description: Unique ID of the Site. example: 8f741bdf-788c-48f7-8ab1-017a826e4521 siteHierarchy: type: string description: Site hierarchy. example: Global/Country1/Site1 siteHierarchyId: type: string description: Site hierarchy ID. example: 8f741bdf-788c-48f7-8ab1-017a826e4521/8f741bdf-788c-48f7-8ab1-017a826e4521 energyConsumed: type: number description: Total energy consumed in kilowatt-hours (kWh). format: double example: 2023 estimatedCost: type: number description: Estimated financial cost associated with the energy consumed, in USD. format: double example: 2524.23 estimatedEmission: type: number description: Estimated total emissions resulting from energy consumption, in kilograms of CO2 equivalent (kg CO2e). format: double example: 513 carbonIntensity: type: number description: Average amount of CO2 emissions per unit of electricity consumed, expressed in gCO2/kWh. format: double example: 123 nuclearEnergyConsumed: type: number description: Amount of energy consumed from nuclear sources, in kWh. format: double example: 100 geothermalEnergyConsumed: type: number description: Amount of energy consumed from geothermal sources, in kWh. format: double example: 10 biomassEnergyConsumed: type: number description: Amount of energy consumed from biomass sources, in kWh. format: double example: 12 coalEnergyConsumed: type: number description: Amount of energy consumed from coal sources, in kWh. format: double example: 17 windEnergyConsumed: type: number description: Amount of energy consumed from wind power sources, in kWh. format: double example: 19 solarEnergyConsumed: type: number description: Amount of energy consumed from solar power sources, in kWh. format: double example: 25 hydroEnergyConsumed: type: number description: Amount of energy consumed from hydropower sources, in kWh. format: double example: 28 gasEnergyConsumed: type: number description: Amount of energy consumed from natural gas sources, in kWh. format: double example: 29 oilEnergyConsumed: type: number description: Amount of energy consumed from oil sources, in kWh. format: double example: 37 unknownEnergyConsumed: type: number description: Amount of energy consumed from unspecified or mixed sources, in kWh. format: double example: 60 hydroDischargeEnergyConsumed: type: number description: Amount of energy consumed through the discharge of hydropower plants, in kWh. format: double example: 21 batteryDischargeEnergyConsumed: type: number description: Amount of energy consumed from the discharge of battery storage systems, in kWh. format: double example: 89 description: Assurance Device Energy Summaries details ClientDeviceEnergyFilters: type: array description: 'List of filters to apply when querying the device energy data. Supported operators are [in, eq, like] ' example: - key: deviceCategory operator: eq value: OtherPOEDevice - key: deviceSubCategory operator: in value: - IEEE PD - IP Phone 7821 - logicalOperator: or filters: - key: deviceCategory operator: eq value: Switch - key: deviceSubCategory operator: in value: - Cisco Catalyst 9300 Switch - Cisco Catalyst 9400 Switch items: $ref: '#/components/schemas/ClientDeviceEnergyFilter' TrendPaginationResponse: type: object properties: limit: type: integer description: The reference to the limit applied in the Pagination Request. example: 500 offset: type: integer description: The reference to the record offset applied in the Pagination Request. example: 1 count: type: integer description: Total number of records related to the resource after applying applicable filtering example: 250 timestampOrder: type: string description: The sort order of the timestamp can be either ascending or descending. enum: - asc - desc description: Pagination response object for trend analytics. Operator: type: string description: Type of filter operator to use for querying data | in and out operator takes multiple values and applies the filters enum: - in - neq - lt - gt - lte - gte - eq - notIn - like DeviceEnergyFilters: type: array description: 'List of filters to apply when querying the device energy data. Supported operators are [in, eq, like] ' example: - key: deviceCategory operator: eq value: Switch - key: deviceSubCategory operator: in value: - Cisco Catalyst 9300 Switch - Cisco Catalyst 9400 Switch - logicalOperator: or filters: - key: deviceCategory operator: eq value: Switch - key: deviceSubCategory operator: in value: - Cisco Catalyst 9300 Switch - Cisco Catalyst 9400 Switch items: $ref: '#/components/schemas/DeviceEnergyFilter' ClientDeviceEnergyView: type: string description: "Views which are supported by this API. Each view represents a specific data set.\n\n### Response data\ \ provided by each view: \n\n1. **device**\n[id, deviceId, deviceCategory, deviceSubCategory] \n\n2. **site**\n\ [id, siteId, siteHierarchy, siteHierarchyId] \n\n3. **energy**\n[id, energyConsumed, estimatedCost, estimatedEmission,\ \ carbonIntensity] \n\n4. **energyMix**\n[nuclearEnergyConsumed, geothermalEnergyConsumed,biomassEnergyConsumed,coalEnergyConsumed,\n\ \ windEnergyConsumed,solarEnergyConsumed,hydroEnergyConsumed\",gasEnergyConsumed,oilEnergyConsumed,unknownEnergyConsumed,hydroDischargeEnergyConsumed,batteryDischargeEnergyConsumed,\ \ fossilFreeEnergyConsumed, renewableEnergyConsumed, fossilEnergyConsumed, nonRenewableEnergyConsumed]\nWhen this\ \ list is not added the default summaries will be: \n\n5. **energySavings**\n[\"energySavings\", \"costSavings\",\ \ \"emissionSavings\"]\n\n**[device, site, energy]**\n" enum: - device - site - energy - energyMix - energySavings DeviceEnergyAttribute: type: string description: Field names which are supported by this API as attributes. enum: - id - deviceName - deviceCategory - deviceSubCategory - connectedDeviceName - connectedInterfaceName - siteId - siteHierarchy - siteHierarchyId - energyConsumed - estimatedCost - estimatedEmission - carbonIntensity - nuclearEnergyConsumed - geothermalEnergyConsumed - biomassEnergyConsumed - coalEnergyConsumed - windEnergyConsumed - solarEnergyConsumed - hydroEnergyConsumed - gasEnergyConsumed - oilEnergyConsumed - unknownEnergyConsumed - hydroDischargeEnergyConsumed - batteryDischargeEnergyConsumed - renewableEnergyConsumed - nonRenewableEnergyConsumed - fossilEnergyConsumed - fossilFreeEnergyConsumed - energySavings - costSavings - emissionSavings DeviceEnergyResponse: type: object properties: attributes: $ref: '#/components/schemas/DeviceEnergyAttributesResponse' aggregateAttributes: $ref: '#/components/schemas/DeviceEnergyAggregateAttributesResponse' groups: type: array items: $ref: '#/components/schemas/DeviceEnergyResponse_groups' description: Response object for device summary analytics. Function: type: string description: Type of aggregate function to apply on the field when querying data example: sum enum: - sum - min - max - avg - count - latest - distinctCount - median DeviceEnergyAggregateAttributeKey: type: string description: Field name on which the aggregate function should be applied when querying the data. The fields supported for aggregation in the API response object are, [energyConsumed, estimatedEmission, estimatedCost, carbonIntensity, deviceCount] enum: - energyConsumed - estimatedEmission - estimatedCost - carbonIntensity - deviceCount - nuclearEnergyConsumed - geothermalEnergyConsumed - biomassEnergyConsumed - coalEnergyConsumed - windEnergyConsumed - solarEnergyConsumed - hydroEnergyConsumed - gasEnergyConsumed - oilEnergyConsumed - unknownEnergyConsumed - hydroDischargeEnergyConsumed - batteryDischargeEnergyConsumed - renewableEnergyConsumed - nonRenewableEnergyConsumed - fossilEnergyConsumed - fossilFreeEnergyConsumed - energySavings - costSavings - emissionSavings NetworkDevicesEnergyResponse: type: object properties: response: type: array description: Successfully returned list of Devices Energy information items: $ref: '#/components/schemas/NetworkDeviceEnergy' page: $ref: '#/components/schemas/NetworkDeviceEnergyPaginationWithAggregateSortBy' version: type: string description: The version of the response example: '2.0' ClientDeviceEnergyResponse: type: object properties: response: $ref: '#/components/schemas/ClientDeviceEnergy' version: type: string description: The version of the response example: '2.0' DeviceEnergySortByObj: type: object properties: name: $ref: '#/components/schemas/DeviceEnergyAttribute' order: type: string description: The sort order of the field ascending or descending. example: asc enum: - asc - desc function: $ref: '#/components/schemas/Function' description: 'This is a unified sortBy model for attributes and aggregate attributes request. If function is specified then API will sort the collection on aggregated attribute. If function is not specified API will sort the collection on attribute. ' NetworkDeviceEnergyResponse: type: object properties: response: $ref: '#/components/schemas/NetworkDeviceEnergy' version: type: string description: The version of the response example: '2.0' ClientDevicesEnergyResponse: type: object properties: response: type: array description: Successfully returned list of Devices Energy information items: $ref: '#/components/schemas/ClientDeviceEnergy' page: $ref: '#/components/schemas/ClientDeviceEnergyPaginationWithAggregateSortBy' version: type: string description: The version of the response example: '2.0' DeviceEnergyAttributesResponse: type: array description: Response object for device summary analytics attributes. items: $ref: '#/components/schemas/DeviceEnergyAttributesResponse_inner' ErrorResponse: title: Error Response type: object properties: response: type: array items: $ref: '#/components/schemas/ErrorObject' version: type: string description: The version of the response example: '1.0' description: Contains information explaining the error that occured processing this request. example: response: - errorCode: 2600 message: Error message detail: Error details externalDocs: description: Error Codes - Cisco DevNet url: https://developer.cisco.com/docs/dna-center/#!api-quick-start/error-codes DeviceEnergyPaginationWithAggregateSortBy: type: object properties: limit: type: integer description: The reference to the limit applied in the Pagination Request. example: 500 offset: type: integer description: "The reference to the record offset applied in the Pagination\n Request." example: 1 count: type: integer description: Total number of records related to the resource after applying applicable filtering example: 12500 sortBy: type: array items: $ref: '#/components/schemas/DeviceEnergySortByObj' description: Pagination model with support for aggregate sort by. DeviceEnergyAggregateAttributesResponse_inner: type: object properties: name: $ref: '#/components/schemas/DeviceEnergyAggregateAttributeKey' function: $ref: '#/components/schemas/Function' value: type: number description: The value for the attribute field in the given time rang example: 78.76 DeviceEnergyGroupBy: type: array description: "List of group by supported. GroupBy should be in a specific sequence ex - deviceCategory, deviceSubCategory\ \ and not deviceSubCategory, deviceCategory \n" example: - deviceCategory - deviceSubCategory items: type: string description: List of field names to group by. enum: - deviceCategory - deviceSubCategory - siteId DeviceEnergyAggregateAttributesResponse: type: array description: Response object for device energy aggregate attributes. items: $ref: '#/components/schemas/DeviceEnergyAggregateAttributesResponse_inner' NetworkDeviceEnergyFilter: type: object properties: key: $ref: '#/components/schemas/NetworkDeviceEnergyFilterKey' operator: $ref: '#/components/schemas/Operator' logicalOperator: $ref: '#/components/schemas/LogicalOperator' value: type: object description: 'Field value(s) to filter the data set. Array of values is used for "in" or "out" operator. Values will be of whatever type the specific field being filtered is defined with. For other operators, filter value is of whatever type the specific field being filtered is defined with. In the case of an "and" or "or" operator, this values array will be ignored, and the values arrays in each of the *nested filters* will be used. ' filters: type: array description: 'Nested array of filters in case of AND/OR based filters. Only one level of nesting will be supported. Structure of nested filter is the same as parent with all operators supported except AND or OR. ' items: $ref: '#/components/schemas/NetworkDeviceEnergyFilter' description: 'In case of single filter, please use `key`, `operator` and `value` combination. If multiple filters need to be applied using a logical operation, please use `logicalOperator` and populate the list of ''filters'' with a combination of FilterObj. Filters can be nested to build complex queries. ' ClientDeviceEnergyQueryRequest: type: object properties: views: type: array example: - device - energy items: $ref: '#/components/schemas/ClientDeviceEnergyView' attributes: type: array example: - deviceCategory - energyConsumed items: $ref: '#/components/schemas/ClientDeviceEnergyAttribute' filters: $ref: '#/components/schemas/ClientDeviceEnergyFilters' aggregateAttributes: type: array items: $ref: '#/components/schemas/DevicesEnergyAggregateAttribute' page: $ref: '#/components/schemas/ClientDeviceEnergyPaginationWithAggregateSortBy' description: Request object for device energy summaries query request. allOf: - $ref: '#/components/schemas/startAndEndTime' ClientDeviceEnergyPaginationWithAggregateSortBy: type: object properties: limit: type: integer description: The reference to the limit applied in the Pagination Request. example: 500 cursor: type: string description: It's an opaque string field that indicates the next record in the requested collection. If no records remain, the API returns a response with a count of zero. The default value is an empty string, and the initial value must be an empty string. The cursor value is populated by the API in the response page block. If the user wants more records, the cursor in the subsequent request must be updated with the value from the previous response. example: eyJ1dWlkX3Rlcm1zIjoiZTBlM2VkMDgtNjE5OS00ZmVmLWFiNDEtZjA4OTcwMTMzYjdkIn0= default: '' count: type: integer description: Total number of records related to the resource after applying applicable filtering example: 12500 sortBy: type: array items: $ref: '#/components/schemas/ClientDeviceEnergySortByObj' description: Pagination model with support for aggregate sort by. DeviceEnergyAttributesResponse_inner: type: object properties: name: $ref: '#/components/schemas/DeviceEnergyAttribute' value: type: object example: sda-c9k-100.cisco.com LogicalOperator: type: string description: 'Operator to use when attempting to apply a logical conjunction of more than 1 filter Logical operations include: ''and'', ''or''. ' enum: - and - or TrendPaginationRequest: type: object properties: limit: type: integer description: The reference to the limit applied in the Pagination Request. example: 500 offset: type: integer description: The reference to the record offset applied in the Pagination Request. example: 1 timestampOrder: type: string description: The sort order of the timestamp can be either ascending or descending enum: - asc - desc description: Pagination request object for trend analytics. DeviceEnergyTrendAnalyticsRequest: type: object properties: filters: $ref: '#/components/schemas/DeviceEnergyFilters' attributes: type: array example: - deviceCategory - energyConsumed items: $ref: '#/components/schemas/DeviceEnergyAttribute' aggregateAttributes: type: array items: $ref: '#/components/schemas/DevicesEnergyAggregateAttribute' groupBy: $ref: '#/components/schemas/DeviceEnergyGroupBy' trendInterval: $ref: '#/components/schemas/DeviceEnergyTrendInterval' page: $ref: '#/components/schemas/TrendPaginationRequest' description: Request object for device energy summaries trend analytics. allOf: - $ref: '#/components/schemas/startAndEndTime' NetworkDeviceEnergyAttribute: type: string description: Field names which are supported by this API as attributes. enum: - id - deviceName - deviceCategory - deviceSubCategory - siteId - siteHierarchy - siteHierarchyId - energyConsumed - estimatedCost - estimatedEmission - carbonIntensity - nuclearEnergyConsumed - geothermalEnergyConsumed - biomassEnergyConsumed - coalEnergyConsumed - windEnergyConsumed - solarEnergyConsumed - hydroEnergyConsumed - gasEnergyConsumed - oilEnergyConsumed - unknownEnergyConsumed - hydroDischargeEnergyConsumed - batteryDischargeEnergyConsumed - renewableEnergyConsumed - nonRenewableEnergyConsumed - fossilEnergyConsumed - fossilFreeEnergyConsumed - energySavings - costSavings - emissionSavings ClientDeviceEnergyFilter: type: object properties: key: $ref: '#/components/schemas/ClientDeviceEnergyFilterKey' operator: $ref: '#/components/schemas/Operator' logicalOperator: $ref: '#/components/schemas/LogicalOperator' value: type: object description: 'Field value(s) to filter the data set. Array of values is used for "in" or "out" operator. Values will be of whatever type the specific field being filtered is defined with. For other operators, filter value is of whatever type the specific field being filtered is defined with. In the case of an "and" or "or" operator, this values array will be ignored, and the values arrays in each of the *nested filters* will be used. ' filters: type: array description: 'Nested array of filters in case of AND/OR based filters. Only one level of nesting will be supported. Structure of nested filter is the same as parent with all operators supported except AND or OR. ' items: $ref: '#/components/schemas/ClientDeviceEnergyFilter' description: 'In case of single filter, please use `key`, `operator` and `value` combination. If multiple filters need to be applied using a logical operation, please use `logicalOperator` and populate the list of ''filters'' with a combination of FilterObj. Filters can be nested to build complex queries. ' NetworkDeviceEnergy: type: object properties: id: type: string description: Unique ID of the Device. example: 8f741bdf-788c-48f7-8ab1-017a826e4521 description: Assurance Network Device Energy Summaries details allOf: - $ref: '#/components/schemas/DeviceEnergy' NetworkDeviceEnergyPaginationWithAggregateSortBy: type: object properties: limit: type: integer description: The reference to the limit applied in the Pagination Request. example: 500 cursor: type: string description: It's an opaque string field that indicates the next record in the requested collection. If no records remain, the API returns a response with a count of zero. The default value is an empty string, and the initial value must be an empty string. The cursor value is populated by the API in the response page block. If the user wants more records, the cursor in the subsequent request must be updated with the value from the previous response. example: eyJ1dWlkX3Rlcm1zIjoiZTBlM2VkMDgtNjE5OS00ZmVmLWFiNDEtZjA4OTcwMTMzYjdkIn0= default: '' count: type: integer description: Total number of records related to the resource after applying applicable filtering example: 12500 sortBy: type: array items: $ref: '#/components/schemas/NetworkDeviceEnergySortByObj' description: Pagination model with support for aggregate sort by. DeviceEnergyTrendAnalyticsResponse: type: object properties: response: type: array description: Successfully returned list of Devices Energy Summaries information grouped by time items: type: object allOf: - $ref: '#/components/schemas/DeviceEnergyResponse' - type: object properties: timestamp: type: number example: 1710435600000 page: $ref: '#/components/schemas/TrendPaginationResponse' version: type: string description: The version of the response example: '2.0' NetworkDeviceEnergyQueryRequest: type: object properties: views: type: array example: - device - energy items: $ref: '#/components/schemas/NetworkDeviceEnergyView' attributes: type: array example: - deviceCategory - energyConsumed items: $ref: '#/components/schemas/NetworkDeviceEnergyAttribute' filters: $ref: '#/components/schemas/NetworkDeviceEnergyFilters' aggregateAttributes: type: array items: $ref: '#/components/schemas/DevicesEnergyAggregateAttribute' page: $ref: '#/components/schemas/NetworkDeviceEnergyPaginationWithAggregateSortBy' description: Request object for device energy summaries query request. allOf: - $ref: '#/components/schemas/startAndEndTime' DevicesEnergyAggregateAttribute: type: object properties: name: $ref: '#/components/schemas/DeviceEnergyAggregateAttributeKey' function: $ref: '#/components/schemas/Function' description: Aggregate attribute object for device energy summaries. Name and function supported are in their respective enum objects. example: name: energyConsumed function: sum CountIntegerResponse: title: Count Integer Response type: object properties: response: $ref: '#/components/schemas/CountIntegerResponse_response' version: type: string description: The version of the response example: '1.0' description: Reports CountIntegerResponse_response: type: object properties: count: type: integer description: The total number of records related to the resource format: int64 example: 1000 ClientDeviceEnergyFilterKey: type: string description: Field names which are supported by this API for filter keys. enum: - id - deviceName - deviceCategory - deviceSubCategory - connectedDeviceName - connectedInterfaceName - siteId - siteHierarchy - siteHierarchyId DeviceEnergySummaryAnalyticsResponse: type: object properties: response: $ref: '#/components/schemas/DeviceEnergyResponse' page: $ref: '#/components/schemas/DeviceEnergyPaginationWithAggregateSortBy' version: type: string description: The version of the response example: '2.0' SiteEnergy: type: object properties: id: type: string description: Unique ID of the Site. example: 8f741bdf-788c-48f7-8ab1-017a826e4521 siteName: type: string description: Site name. example: Site1 siteHierarchy: type: string description: Site hierarchy. example: Global/Country1/Site1 siteHierarchyId: type: string description: Site hierarchy ID. example: 8f741bdf-788c-48f7-8ab1-017a826e4521/8f741bdf-788c-48f7-8ab1-017a826e4521 siteType: type: string description: 'Type of site For aggregation requests, the value may be null since the unique identifier may not apply ' enum: - floor - building - area - global latitude: type: number description: Longitude of the site. format: long example: 37.418652 longitude: type: number description: Longitude of the site. format: long example: 121.919367 deviceCategories: type: array description: Device categories. items: type: string format: string energyConsumed: type: number description: Total energy consumed in kWh. example: 2023 estimatedCost: type: number description: Estimate of the total financial cost. example: 2524.23 estimatedEmission: type: number description: Estimate of the total emission in kg CO2. example: 513 carbonIntensity: type: number description: Carbon intensity. example: 123 numberOfDevices: type: number description: 'number of devices for the sites that are returning energy data. ' description: Assurance site and corresponding energy details SiteEnergyFilterKey: type: string description: Field names which are supported by this API for filter keys. enum: - id - siteName - siteHierarchy - siteHierarchyId - siteType - latitude - longitude - numberOfDevices - deviceCategory SiteEnergyPaginationWithAggregateSortBy: type: object properties: limit: type: integer description: The reference to the limit applied in the Pagination Request. example: 500 offset: type: integer description: "The reference to the record offset applied in the Pagination\n Request." example: 1 count: type: integer description: Total number of records related to the resource after applying applicable filtering example: 12500 sortBy: type: array items: $ref: '#/components/schemas/SiteEnergySortByObj' description: Pagination model with support for aggregate sort by. example: limit: 100 offset: 1 sortBy: - name: energyConsumed order: desc function: sum SitesEnergyResponse: type: object properties: response: type: array description: Successfully returned list of Sites Energy information items: $ref: '#/components/schemas/SiteEnergy' page: $ref: '#/components/schemas/SiteEnergyPaginationWithAggregateSortBy' version: type: string description: The version of the response example: '2.0' SiteEnergyFilter: type: object properties: key: $ref: '#/components/schemas/SiteEnergyFilterKey' operator: $ref: '#/components/schemas/Operator' logicalOperator: $ref: '#/components/schemas/LogicalOperator' value: type: object description: 'Field value(s) to filter the data set. Array of values is used for "in" or "out" operator. Values will be of whatever type the specific field being filtered is defined with. For other operators, filter value is of whatever type the specific field being filtered is defined with. In the case of an "and" or "or" operator, this values array will be ignored, and the values arrays in each of the *nested filters* will be used. ' filters: type: array description: 'Nested array of filters in case of AND/OR based filters. Only one level of nesting will be supported. Structure of nested filter is the same as parent with all operators supported except AND or OR. ' items: $ref: '#/components/schemas/SiteEnergyFilter' description: 'In case of single filter, please use `key`, `operator` and `value` combination. If multiple filters need to be applied using a logical operation, please use `logicalOperator` and populate the list of ''filters'' with a combination of FilterObj. Filters can be nested to build complex queries. ' SitesEnergyQueryRequest: type: object properties: views: type: array example: - site - energy items: $ref: '#/components/schemas/SiteEnergyView' attributes: type: array example: - estimatedEmission - energyConsumed items: $ref: '#/components/schemas/SiteEnergyAttribute' filters: $ref: '#/components/schemas/SiteEnergyFilters' aggregateAttributes: type: array items: $ref: '#/components/schemas/SiteEnergyAggregateAttribute' page: $ref: '#/components/schemas/SiteEnergyPaginationWithAggregateSortBy' allOf: - $ref: '#/components/schemas/startAndEndTime' SiteEnergyAggregateAttributeKey: type: string description: Field name on which the aggregate function should be applied when querying the data. The fields supported for aggregation in the API response object are, [energyConsumed, estimatedEmission, estimatedCost, carbonIntensity] enum: - energyConsumed - estimatedEmission - estimatedCost - carbonIntensity - numberOfDevices SiteEnergyFilters: type: array description: 'List of filters to apply when querying the site energy data. Supported operators are [in, eq, like] ' example: - key: siteHierarchy operator: eq value: Global/Ottawa - key: siteHierarchyId operator: in value: - /57df4064-82d8-4314-8059-00aaf146e6fe/20e0a1db-96ec-4b3e-b787-827edd12dc1e/ - /57df4064-82d8-4314-8059-00aaf146e6fe/ - logicalOperator: or filters: - key: siteHierarchy operator: like value: Global/.* - key: siteHierarchyId operator: eq value: /57df4064-82d8-4314-8059-00aaf146e6fe/20e0a1db-96ec-4b3e-b787-827edd12dc1e/ items: $ref: '#/components/schemas/SiteEnergyFilter' SiteEnergyAggregateAttributesResponse: type: array items: $ref: '#/components/schemas/SiteEnergyAggregateAttributesResponse_inner' SiteEnergyAggregateAttribute: type: object properties: name: $ref: '#/components/schemas/SiteEnergyAggregateAttributeKey' function: $ref: '#/components/schemas/Function' example: name: energyConsumed function: sum SiteEnergyAggregateAttributesResponse_inner: type: object properties: name: $ref: '#/components/schemas/SiteEnergyAggregateAttributeKey' function: $ref: '#/components/schemas/Function' value: type: number description: The value based on the functions requested in the input data SiteEnergyView: type: string description: "Views which are supported by this API. Each view represents a specific data set.\n\n### Response data\ \ provided by each view: \n\n1. **Site**\n[id, siteHierarchy, siteHierarchyId, siteType, latitude, longitude] \n\ \n2. **Energy**\n[energyConsumed, estimatedCost, estimatedEmission, carbonIntensity] \n\nWhen this list is not added\ \ the default summaries will be: \n\n**[site,energy]**\n" enum: - site - energy asyncInfoContainer: properties: response: $ref: '#/components/schemas/asyncInfo' version: type: string example: '1.0' description: 'Generic model that will contain the asynchronous task/process information ' asyncInfo: properties: taskLocation: type: string description: url resource where the client can fetch their task's lifecycle updates example: /dna/data/api/v1/assuranceTasks/bcbb2a8c-deae-4a3e-9459-0eb1dc12c191 taskId: type: string description: the specific task id associated with the specific request made example: bcbb2a8c-deae-4a3e-9459-0eb1dc12c191 description: "Generic model with information on the asynchronous task/process\n that was created to handle an API request\n" SiteEnergySortByObj: type: object properties: name: $ref: '#/components/schemas/SiteEnergyAttribute' order: type: string description: The sort order of the field ascending or descending. example: asc enum: - asc - desc function: $ref: '#/components/schemas/Function' description: 'This is a unified sortBy model for attributes and aggregate attributes request. If function is specified then API will sort the collection on aggregated attribute. If function is not specified API will sort the collection on attribute. ' SiteEnergyAttribute: type: string description: Field names which are supported by this API as attributes or filter keys enum: - id - siteName - siteHierarchy - siteHierarchyId - siteType - latitude - longitude - numberOfDevices - deviceCategories - energyConsumed - estimatedCost - estimatedEmission - carbonIntensity SitesEnergyQueryResponse: type: object properties: response: type: array description: Successfully returned list of Sites Energy information items: allOf: - $ref: '#/components/schemas/SiteEnergy' - type: object properties: aggregateAttributes: $ref: '#/components/schemas/SiteEnergyAggregateAttributesResponse' description: Response object for site energy summaries query API. page: $ref: '#/components/schemas/SiteEnergyPaginationWithAggregateSortBy' version: type: string description: The version of the response example: '2.0' SiteEnergyResponse: type: object properties: response: $ref: '#/components/schemas/SiteEnergy' version: type: string description: The version of the response example: '2.0' examples: QueryWithViewPassedResponseExample: summary: QueryWithViewPassedResponse value: response: - id: f4b8bceb-588b-490c-b726-3dd8caf65071 deviceId: f4b8bceb-588b-490c-b726-3dd8caf65071 deviceName: ott-sda-c9k-01.cisco.com deviceCategory: Switch deviceSubCategory: Cisco Catalyst 9300 Switch page: limit: 100 cursor: '' count: 1 version: '1.0' QueryWithViewPassedRequestExample: summary: QueryWithViewPassedRequest value: startTime: 1703195600000 endTime: 1707800400000 filters: - key: id value: - f4b8bceb-588b-490c-b726-3dd8caf65071 operator: in views: - device attributes: - deviceCategory page: limit: 100 cursor: '' SummaryAnalyticsWithGroupByResponseExample: summary: SummaryAnalyticsWithGroupByResponse value: response: attributes: [] aggregateAttributes: [] groups: - id: siteId=12345678 attributes: - name: siteHierarchy value: Global/Ottawa - name: deviceCategory value: Switches and Hubs aggregateAttributes: - name: energyConsumed function: sum value: 55.12 page: - limit: 2 offset: 1 count: 20 sortBy: - name: name order: asc ClientDeviceQueryWithoutViewPassedResponseExample: summary: QueryWithoutViewPassedResponse value: response: - id: 00:7E:95:79:99:17 deviceName: SEP007E95799917 connectedDeviceName: ott-sda-c9k-21.cisco.com, connectedInterfaceName: GigabitEthernet1/1/0, deviceCategory: OtherPOEDevice, deviceSubCategory: IP Phone 7821, siteId: 8f741bdf-788c-48f7-8ab1-017a826e4521, siteHierarchy: Global/Country1/Site1, siteHierarchyId: 8f741bdf-788c-48f7-8ab1-017a826e4521/8f741bdf-788c-48f7-8ab1-017a826e4521, energyConsumed: 2023, estimatedCost: 2524.23, estimatedEmission: 513, carbonIntensity: 123 aggregateAttributes: - name: energyConsumed function: sum value: 251895 page: limit: 100 cursor: '' count: 1 version: '1.0' QueryWithoutViewPassedResponseExample: summary: QueryWithoutViewPassedResponse value: response: - id: d77de6d8-aad9-4f45-8eca-d1abc1334e1a deviceName: ott-sda-c9k-21.cisco.com deviceCategory: Switch deviceSubCategory: Cisco Catalyst 9300 Switch siteId: 1af85e89-d976-4773-b87c-0a4b5235e028 siteHierarchy: Global/Ottawa/3000 innovation siteHierarchyId: /4f92c9ba-4602-4a32-a3f0-ded242897884/a1029e8d-f397-4e7d-94c6-bcf140c2474f/1af85e89-d976-4773-b87c-0a4b5235e028/ energyConsumed: 123.75 estimatedCost: 0 estimatedEmission: 2284.25 carbonIntensity: 1.5 aggregateAttributes: - name: energyConsumed function: sum value: 251895 page: limit: 100 cursor: '' count: 1 version: '1.0' TrendAnalyticsWithGroupByRequestExample: summary: TrendAnalyticsWithGroupByRequest value: startTime: 1705348800000 endTime: 1705348800000 trendInterval: 5MIN groupBy: - deviceCategory attributes: [] filters: - key: siteHierarchy operator: eq value: Global/Ottawa aggregateAttributes: - name: energyConsumed function: sum page: limit: 2 offset: 1 timestampOrder: desc SummaryAnalyticsWithGroupByRequestExample: summary: SummaryAnalyticsWithGroupByRequest value: startTime: 1705348800000 endTime: 1705435200000 groupBy: - siteId attributes: - name - deviceCategory filters: - key: siteHierarchy operator: eq value: Global/Ottawa aggregateAttributes: - name: energyConsumed function: sum page: limit: 2 offset: 1 sortBy: - name: energyConsumed order: asc function: sum TrendAnalyticsWithGroupByResponseExample: summary: TrendAnalyticsWithGroupByResponse value: response: - timestamp: 1705348800000 attributes: [] aggregateAttributes: [] groups: - id: deviceCategory=Switch attributes: - name: deviceCategory value: Switch aggregateAttributes: - name: energyConsumed function: sum value: 30 - id: deviceCategory=OtherPOEDevies attributes: - name: deviceCategory value: OtherPOEDevies aggregateAttributes: - name: energyConsumed function: sum value: 7 - id: deviceCategory=Wireless attributes: - name: deviceCategory value: Wireless aggregateAttributes: - name: energyConsumed function: sum value: 2 - timestamp: 1705348500000 attributes: [] aggregateAttributes: [] groups: - id: deviceCategory=Switch attributes: - name: deviceCategory value: Switch aggregateAttributes: - name: energyConsumed function: sum value: 43 - id: deviceCategory=OtherPOEDevies attributes: - name: deviceCategory value: OtherPOEDevies aggregateAttributes: - name: energyConsumed function: sum value: 8 - id: deviceCategory=Wireless attributes: - name: deviceCategory value: Wireless aggregateAttributes: - name: energyConsumed function: sum value: 5 page: limit: 2 offset: 1 count: 250 timestampOrder: desc SummaryAnalyticsWithoutGroupByRequestExample: summary: SummaryAnalyticsWithoutGroupByRequest value: startTime: 1705348800000 endTime: 1705435200000 groupBy: [] attributes: [] filters: - key: siteHierarchy operator: eq value: Global/Ottawa aggregateAttributes: - name: energyConsumed function: sum page: limit: 100 offset: 1 sortBy: [] TrendAnalyticsWithoutGroupByResponseExample: summary: TrendAnalyticsWithoutGroupByResponse value: response: - timestamp: 1705348800000 attributes: - name: energyConsumed value: 31 aggregateAttributes: [] groups: [] - timestamp: 1705348500000 attributes: - name: energyConsumed value: 15 aggregateAttributes: [] groups: [] page: limit: 2 offset: 1 count: 250 timestampOrder: desc SummaryAnalyticsWithoutGroupByResponseExample: summary: SummaryAnalyticsWithoutGroupByResponse value: response: attributes: [] aggregateAttributes: - name: energyConsumed function: sum value: 1002.3 groups: [] page: - limit: 100 offset: 1 count: 1 TrendAnalyticsWithoutGroupByRequestExample: summary: TrendAnalyticsWithoutGroupByRequest value: startTime: 1705348800000 endTime: 1705348800000 trendInterval: 5MIN attributes: - energyConsumed groupBy: [] filters: - key: siteHierarchy operator: eq value: Global/Ottawa aggregateAttributes: [] page: limit: 2 offset: 1 timestampOrder: desc QueryWithoutViewPassedRequestExample: summary: QueryWithoutViewPassedRequest value: startTime: 1703195600000 endTime: 1707800400000 filters: - key: id value: - f4b8bceb-588b-490c-b726-3dd8caf65071 operator: in views: [] attributes: [] page: limit: 100 cursor: '' SiteEnergyQueryAPIWithViewPassedRequestExample: summary: SiteEnergyQueryAPIWithViewPassedRequestExample value: startTime: 1710959466452 endTime: 1713210303205 filters: - key: siteHierarchyId operator: like value: /9722c7e7-90c5-4af0-a77b-fa007f391f64/bba8d2b8-f3cb-45bd-9a0c-ded436246e0e.* attributes: [] views: - site - energy aggregateAttributes: - name: energyConsumed function: sum page: limit: 100 offset: 1 sortBy: - name: energyConsumed order: desc function: sum SiteEnergyQueryAPIWithViewPassedResponseExample: summary: SiteEnergyQueryAPIWithViewPassedRequestExample value: response: - siteId: dc55b6c0-fc6f-4362-8078-9487c6d1119d siteHierarchy: Global/Canada/Ottawa/2000 innovation siteHierarchyId: /9722c7e7-90c5-4af0-a77b-fa007f391f64/bba8d2b8-f3cb-45bd-9a0c-ded436246e0e/1cc17af5-387f-4fa9-82f9-b74bdc24df6b/dc55b6c0-fc6f-4362-8078-9487c6d1119d/ siteType: building latitude: 45.342065 longitude: -75.926259 deviceCategories: - Switch - AccessPoint - OtherPOEDevices numberOfDevices: 6 parentSiteId: 1cc17af5-387f-4fa9-82f9-b74bdc24df6b energyConsumed: 135423 estimatedCost: 724.5 estimatedEmission: 611.24 carbonIntensity: 44.508 aggregateAttributes: - name: energyConsumed function: sum value: 191697 - siteId: 1cc17af5-387f-4fa9-82f9-b74bdc24df6b siteHierarchy: Global/Canada/Ottawa siteHierarchyId: /9722c7e7-90c5-4af0-a77b-fa007f391f64/bba8d2b8-f3cb-45bd-9a0c-ded436246e0e/1cc17af5-387f-4fa9-82f9-b74bdc24df6b/ siteType: area deviceCategories: - Switch - AccessPoint - OtherPOEDevices numberOfDevices: 6 parentSiteId: bba8d2b8-f3cb-45bd-9a0c-ded436246e0e energyConsumed: 135423 estimatedCost: 724.5 estimatedEmission: 611.24 carbonIntensity: 44.508 aggregateAttributes: - name: energyConsumed function: sum value: 191697 - siteId: bba8d2b8-f3cb-45bd-9a0c-ded436246e0e siteHierarchy: Global/Canada siteHierarchyId: /9722c7e7-90c5-4af0-a77b-fa007f391f64/bba8d2b8-f3cb-45bd-9a0c-ded436246e0e/ siteType: area deviceCategories: - Switch - AccessPoint - OtherPOEDevices numberOfDevices: 6 parentSiteId: 9722c7e7-90c5-4af0-a77b-fa007f391f64 energyConsumed: 135423 estimatedCost: 724.5 estimatedEmission: 611.24 carbonIntensity: 44.508 aggregateAttributes: - name: energyConsumed function: sum value: 191697 page: limit: 100 offset: 1 count: 6 sortBy: - name: energyConsumed order: desc function: sum version: '1.0' externalDocs: description: Catalyst Center Developer API resources url: https://developer.cisco.com/dnacenter/ x-refined-from: - cisco-catalyst-center-device-energy-openapi.yml - cisco-catalyst-center-sites-energy-openapi.yml