--- title: Hyperglance Inventory API Reference description: Technical Reference --- [Skip to content](https://support.hyperglance.com/knowledge/hyperglance-api-documentation#main-content) English Show submenu for translations [More support](https://support.hyperglance.com/knowledge/kb-tickets/new?hsLang=en) ![](https://support.hyperglance.com/hs-fs/hubfs/hyperglance.png?width=100&height=75&name=hyperglance.png) Open main navigation Close main navigation - English Show submenu for translations - [More support](https://support.hyperglance.com/knowledge/kb-tickets/new) - [Contact Us](https://www.hyperglance.com/contact/) [Contact Us](https://www.hyperglance.com/contact/) How can we help you? - There are no suggestions because the search field is empty. 1. [Hyperglance Support](https://support.hyperglance.com/knowledge?hsLang=en) 2. [Setup & Configuration](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en) 3. [API](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#api) # Hyperglance Inventory API Reference ## Technical Reference ### Table of Contents - [Getting Started](https://support.hyperglance.com/knowledge/hyperglance-api-documentation#overview) - [Concepts & Terminology](https://support.hyperglance.com/knowledge/hyperglance-api-documentation#concepts-and-terminology) - [APIs](https://support.hyperglance.com/knowledge/hyperglance-api-documentation#hgapi-reference) - [Network API - (Get Inventory Graph)](https://support.hyperglance.com/knowledge/hyperglance-api-documentation#get-network) - [Augmentation API - (Attach custom attributes, Hyperlinks or tag-views)](https://support.hyperglance.com/knowledge/hyperglance-api-documentation#augment-attributes)   ### Getting Started The Hyperglance API is exposed on: **https://\/hgapi** All paths in this document are relative to that root URL. To use this API you must [generate an API key](https://support.hyperglance.com/knowledge/getting-started-with-the-hyperglance-api?hsLang=en) and use it to authenticate by passing it as an HTTP Authorization header (for details see [Authentication)](https://support.hyperglance.com/knowledge/authentication?hsLang=en). ### Concepts & Terminology | Datasource | A datasource is a unique name assigned to an HGAPI application and so serves to identify the source of topology data in Hyperglance (e.g. Amazon, Azure, Kubernetes). Your HGAPI application has a single datasource name. You will usually want to hard-code this into your application. Examples: "AcmeApp", “OpenStack”, "John's MongoDb" | | --- | --- | | Topology | A topology is a well-formed piece of the overall Network and could be a single AWS Account, Azure Subscription or Kubernetes cluster. | | Groups | A kind of entity that appears in the Hyperglance diagram as a box with an icon that can contain nested parts of the topology. Examples: Regions, Subnets | | Nodes | A kind of entity often used to model network devices or top-level concepts. Examples: Load-Balancers, NAT Gateways | | Endpoints | A kind of entity often used to model network interface or other hardware elements. An endpoint maybe be attached to a Node or a Group. Examples: Network Interface Cards, Ports, Logical Disk Partitions. | | Links | A kind of entity often used to model connectivity or relationships between groups, nodes and endpoints and always spans between two points in the diagram. Examples: Routing links, links between VM and Loadbalancers | | Alarms | A kind of entity often used to model alarms/alerts/problems. An alarm always belongs to either a node or an endpoint. Examples: High CPU Alarm, Service Down Alarm. | | Attributes | Textual key/value data. All nodes, endpoints and links support attributes. | | Types | Every kind of entity (Node, Endpoint, Link, Group, etc) has a type. A type can be any string and is used to indicate the user about the particular ‘type’ of Node (or Endpoint/Link/Group/Alarm) that they are looking at. Examples: vm, host, switch, router, connection | | Keys | A type of local ID used by Hyperglance which often matches with the original cloud resource's identifier (e.g. an instance-id). | | Unique IDs (UIDs) | An ID built by Hyperglance for every entity in the inventory and is completely unique within the entire inventory. The format and structure of UID strings is undefined and subject to change. **Do not depend on it.** | ### APIs All paths are specified relative to the HGAPI’s root endpoint URL, see “Getting Started” section. #### Network API ***GET /network*** Returns the inventory graph of Hyperglance inluding all groups, nodes, links and so on. **Normal response codes:** 200 OK **Error response codes:** 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found **Example response:** | { "updatedAt": 123456789, "topologies": \[ { "name": "example topology", "datasource": "AcmeApp", "nodes": \[ { "UID": "902c-8ce241a85bbb", "key": "node1", "name": "new-vm-test", "type": "vm", "attributes": \[ { "name": "Company", "value": "Acme Corp." } \], "groupKey": "g1" }, { "UID": "9421-8bb2a8139669", "key": "node2", "name": "lab host1", "type": "host", "attributes": \[ { "name": "Company", "value": "Acme Corp." } \], "groupKey": "g1" } \], "endpoints": \[ { "UID": "8c73-e7f06f359a1f", "key": "ep1", "name": "ep1", "type": "virtual port", "attributes": \[\], "ownerUID": "902c-8ce241a85bbb" }, { "UID": "988a-60aa3b19f13a", "key": "ep2", "name": "ep2", "type": "physical port", "attributes": \[\], "ownerUID": "9421-8bb2a8139669" } \], "links": \[ { "UID": "becd-5c6d4c62b09c", "key": "link1", "name": "link1", "type": "virtual\<-\>physical connection", "attributes": \[\], "nodeAUID": "902c-8ce241a85bbb", "nodeBUID": "9421-8bb2a8139669", "endpointAUID": "8c73-e7f06f359a1f", "endpointBUID": "988a-60aa3b19f13a" } \], "alarms": \[ { "UID": "898e-87ef7fed4dff", "key": "alarm1", "name": "High CPU", "type": "metric alarm", "attributes": \[ { "name": "Description", "value": "CPU exceeded threshold!" } \], "ownerUID": "902c-8ce241a85bbb", "severity": "CRITICAL" } \], "groups": \[ { "UID": "AcmeApp\|example topology\|GROUP\|VPC\|g1", "key": "g1", "type": "VPC", "name": "group1", "appTags": \[\], "attributes": \[ { "name": "Description", "value": "Small subset of Topology" } \], "dependsOnNodeKeys": \[\], "urls": \[\], "parentGroupKey": null } \] } \] } | | --- | **JSON elements:** | **updatedAt** | Integer | Time the Network was last updated. Unit: Seconds since Unix Epoch. | | --- | --- | --- | | **topologies** | List of Topologies | All topologies contributed by a data-source. Absent from these topologies are any non-creatable entities. | | **datasource** | String | The data-source identifier. | | **name** | String | Name of topology (e.g. account or subscription alias) | | **nodes** | List of Nodes | Nodes in a topology. | | **endpoints** | List of Endpoints | Endpoints in a topology. | | **links** | List of Links | Links in a topology. | | **alarms** | List of Alarms | Alarms in a topology. | | **groups** | List of groups | Groups in a topology. | | **UID** | UID String | The UID of the Node, Endpoint, Link or Alarm. | | **key** | String | The Key of the Node, Endpoint, Link or Alarm. | | **type** | String | The Type of the Node, Endpoint, Link or Alarm. | | **groupKey** | String | The group name of the node. | | **parentGroupKey** | String | The group name of the child group. | | **name** | String | The name of a Node, Endpoint, Link or Alarm. | | **attributes** | List of Attributes | Attributes of the Node, Endpoint, Link, Alarm or Group. | | **name** | String | The name of an Attribute. | | **value** | String | The value of an Attribute. | | **ownerUID** | UID String | The UID of the Node/Group that an Endpoint attaches to. | | **nodeAUID** | UID String | The UID of a Node that a Link attaches to. | | **nodeBUID** | UID String | The UID of a Node that a Link attaches to. | | **endpointAUID** (optional) | UID String | The UID of an Endpoint that a Link attaches to. | | **endpointBUID** (optional) | UID String | The UID of an Endpoint that a Link attaches to. | | **ownerUID** | UID String | The UID of a Node or Endpoint that an Alarm attaches to. | | **severity** | String | The severity of an Alarm. One of: **CRITICAL**, **SEVERE**, **WARNING**, **INFO**. |   **Example Scripts:** - [https://github.com/hyperglance/api-samples/blob/master/python/diagram-to-json.py](https://github.com/hyperglance/api-samples/blob/master/python/diagram-to-json.py) #### Augmentation API ***PUT /augment*** Allows for attach custom attributes, custom hyperlinks and custom apptags (for [tag-views](https://support.hyperglance.com/knowledge/tag-view?hsLang=en)) onto resource items in Hyperglance. You will be able to see your attributes, hyperlinks and tag-views in the Hyperglance UI. **Normal response codes:** 200 OK, 202 Accepted **Error response codes:** 400 Bad Request, 401 Unauthorized, 403 Forbidden **Example request:** | { "appTags": \[ { "UID": "acda-dee6d506a1db", "appTags": \["AugmentedAppTag1", "AugmentedAppTag2"\] } \], "attributes": \[ { "UID": "acda-dee6d506a1db", "attributes": \[ { "name": "Contact E-Mail", "value": "jon@example.com" } \] } \], "urls":\[ { "UID": "acda-dee6d506a1db", "urls":\[ { "displayName":"Hyperglance", "urlPath":"https://twitter.com/hyperglance" } \] } \] } | | --- | **JSON elements:** | **attributes** | List of Attribute-Augmentations | Attribute-Augmentations to apply. Any Attribute-Augmentations created prior by this API Key will be replaced. | | --- | --- | --- | | **urls** | List of URL-Augmentations | URL-Augmentations to apply. Any URL-Augmentations created prior by this API Key will be replaced. | | **appTags** | List of AppTag-Augmentations | AppTag-Augmentations to apply. Any Attribute-Augmentations created prior by this API Key will be replaced. | | **UID** | UID String | The UID of a Node, Endpoint, Link, Alarm or Group receiving the augmentation. | | **attributes** | List of Attributes | Attribute Key and Value pairs to attach to the intended resource. | | **urls** | List of URLs | Hyperlinks to attach to the intended resource. | | **appTags** | List of Strings | App Tag names to attach to the intended resource. | | **name** | String | The name of an attribute. | | **value** | String | The value of an attribute. | | **displayName** | String | The hyperlink text that will be shown in the Hyperglance UI. | | **urlPath** | String | The hyperlink URL. | **Example Scripts:** - [https://github.com/hyperglance/api-samples/blob/master/python/augment\_attributes.py](https://github.com/hyperglance/api-samples/blob/master/python/augment_attributes.py) - [https://github.com/hyperglance/api-samples/blob/master/python/augment\_urls.py](https://github.com/hyperglance/api-samples/blob/master/python/augment_urls.py) - [https://github.com/hyperglance/api-samples/blob/master/python/augment\_appTags.py](https://github.com/hyperglance/api-samples/blob/master/python/augment_appTags.py) - [https://github.com/hyperglance/api-samples/blob/master/python/augment\_attributes\_appTags\_urls.py](https://github.com/hyperglance/api-samples/blob/master/python/augment_attributes_appTags_urls.py) - [Before You Start](https://support.hyperglance.com/knowledge/before-you-start?hsLang=en#main-content) - [Kubernetes](https://support.hyperglance.com/knowledge/before-you-start?hsLang=en#kubernetes) - [GCP](https://support.hyperglance.com/knowledge/before-you-start?hsLang=en#gcp) - [AWS](https://support.hyperglance.com/knowledge/before-you-start?hsLang=en#aws) - [Azure](https://support.hyperglance.com/knowledge/before-you-start?hsLang=en#azure) - [Using Hyperglance](https://support.hyperglance.com/knowledge/using-hyperglance?hsLang=en#main-content) - [Automations](https://support.hyperglance.com/knowledge/using-hyperglance?hsLang=en#automations) - [Inventory & Diagrams](https://support.hyperglance.com/knowledge/using-hyperglance?hsLang=en#inventory-diagrams) - [Rules](https://support.hyperglance.com/knowledge/using-hyperglance?hsLang=en#rules) - [Cost Management](https://support.hyperglance.com/knowledge/using-hyperglance?hsLang=en#cost-management) - [Dashboards](https://support.hyperglance.com/knowledge/using-hyperglance?hsLang=en#dashboards) - [Security & Compliance](https://support.hyperglance.com/knowledge/using-hyperglance?hsLang=en#security-compliance) - [Setup & Configuration](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#main-content) - [Updating & Migrating](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#updating-migrating) - [General](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#general) - [RBAC & Users](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#rbac-users) - [STIGS & FIPS](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#stigs-fips) - [AWS](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#aws) - [Azure](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#azure) - [Kubernetes](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#kubernetes) - [GCP](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#gcp) - [API](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#api) - [Legacy Docker-based deployments](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#legacy-docker-based-deployments) - [AI](https://support.hyperglance.com/knowledge/setup-configuration?hsLang=en#ai) [![Chill listening crop-3](https://support.hyperglance.com/hs-fs/hubfs/hyperglance.png?width=134&height=24&name=hyperglance.png "Chill listening crop-3")](https://www.hyperglance.com/) 2880 Zanker Road, Suite 203, San Jose, CA 95134 Copyright © 2025 Hyperglance. All rights reserved.