Skip to content

Entities resources

The API allows you to search for your entities and devices in Virtana Service Observability.

Resource list

Authentication

All Virtana Service Observability API endpoints require HTTPS, expect JSON in the request body when a body is required, and return a JSON response. You must have an authentication key to send requests to a Virtana Service Observability API endpoint. The key is sent in the zenoss-api-key header of each request. For the maintenance windows APIs you must use a key generated from a User API type API client.

All of the following API examples use curl to send a JSON request from a Bash shell to an endpoint. All examples use YOUR-API-ENDPOINT and YOUR-API-KEY as placeholders for endpoints and authentication keys.

POST /v1/modelcontext/entities:search

This endpoint allows you to search for devices by the criteria you specify.

  • search_input: Required. Used to provide the query, sort_by options, page_input options, and group_by options.

  • fields: Optional. Specify which fields you want returned for the matching entities. If omitted, default well-known fields will be returned.

Request template

This section provides an abstract preview of the JSON request used to search for an entity.

{
  "search_input": {
    "sortby": [
      {
        "field_kind": 1,
        "field": "_id",
        "order": 1
      }
    ],
    "page_input": {
      "limit": 10
    },
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "coreProperties.name",
                "value": "10.88.122.130",
                "operation": 1
              }
            },
            {
              "in": {
                "field": "schemaIds",
                "values": [
                  "Base.Device"
                ]
              }
            }
          ]
        }
      }
    }
  }
}

Request fields

search_input (object, required)

Criteria for search, using query.

query (object, required)
Specify entities using search criteria.
page_input (object, optional)

Page selection criteria.

limit (number, optional)
Limit of results.
cursor (string, optional)
EndCursor from previous page results.

Response fields

entities
Array of entity objects that match the search criteria specified for that tenant.
pageInfo
Object with startCursor and endCursor fields among others. EndCursor can be used to get remaining entities.

Status codes

  • 200 (success)
  • 400 (invalid request, for example, search input was empty)
  • 500 (internal server error)

Example

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/entities:search \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
      "search_input": {
        "page_input": {
        "limit": 10
        },
        "query": {
            "clause": {
                "and": {
                "clauses": [
                    {
                    "filter": {
                        "field": "coreProperties.name",
                        "value": "10.88.122.130",
                        "operation": 1
                    }
                    },
                    {
                    "in": {
                        "field": "schemaIds",
                        "values": [
                        "Base.Device"
                        ]
                    }
                    }
                ]
                }
            }
        }
    }
}'

{
    "entities": {
        "entities": [
        {
            "id": "AAAAAzxIDQsTlnweGQ04by62PDA=",
            "factIds": [],
            "schemaIds": [
            "Base.Device"
            ],
            "name": "10.88.122.130",
            "timestamp": "1775440665000",
            "tenant": "svc",
            "fields": null,
            "dimensions": {
            "contextUUID": "672267b5-d86a-4600-b96f-97cfc0a7997a",
            "source": "cz0"
            },
            "coreProperties": {
            "HWManufacturer": [
                "VMware, Inc."
            ],
            "HWModel": [
                "VMware Virtual Platform"
            ],
            "HWSerialNumber": [
                "00376-30000-00299-AA408"
            ],
            "HWTag": [
                "System Enclosure 0"
            ],
            "OSManufacturer": [
                "Microsoft Corporation"
            ],
            "OSModel": [
                "Windows Server 2016 Standard"
            ],
            "_zen_direct_entity_id": [
                "AAAAAzxIDQsTlnweGQ04by62PDA="
            ],
            "_zen_impactedEntities": [
                "AAAAA-H8aY6Ii7eeXv2bcbb8HGY=",
                "AAAAA-maSR2oySfT79lSWYgKFi4=",
                "AAAAA0SgtV8XWS_-aoCLuH6QUlY=",
                "AAAAA1O0v211bKH38ttlg76vesI=",
                "AAAAA1xRi1M670LmjiG_4xCznlQ=",
                "AAAAA2tKhBdYxIOAKnFywb-wBXY=",
                "AAAAA3UEOvORDWGyMFgq5f21c_w=",
                "AAAAA3ZffC58Bkj8l7XDP8dYmdU=",
                "AAAAA3t3fwgIz3g6eVZt9DsI4MI=",
                "AAAAA45Ov77K58ugWQKzX_0hQ8k=",
                "AAAAA4MWJPjciJpxPDsfMk8YNgg=",
                "AAAAA50ozsZyj3KahqL8O_heMtA=",
                "AAAAA9hTin5YMA5Tjin8V_XXLSk=",
                "AAAAA_eyR6MJFRd_bA1D5ksk9kw=",
                "AAAAA_jsDndSqMQmcv3M4hrSEVc=",
                "AAAAAwy65UsQ5giiBHCifRc4M5Q=",
                "AAAAAx333V2kevTC38BS2cAdHjs="
            ],
            "_zen_parent_entity_id": [
                "AAAAA-H8aY6Ii7eeXv2bcbb8HGY="
            ],
            "_zen_schemaIds": [
                "Base.Device"
            ],
            "_zen_tenant_id": [
                "dwgywhbbjomrhbtg"
            ],
            "_zorgs_device_class": [
                "/Server/Microsoft/Cluster/ZenossQA"
            ],
            "_zorgs_groups": [
                "/moreThan40"
            ],
            "contextUUID": [
                "672267b5-d86a-4600-b96f-97cfc0a7997a"
            ],
            "device": [
                "10.88.122.130"
            ],
            "name": [
                "10.88.122.130"
            ],
            "parent": [
                "06f442aa-73de-4571-b0ab-8b82631b0585"
            ],
            "source": [
                "cz0"
            ],
            "source-type": [
                "cz"
            ]
            },
            "createTime": "1713148087000",
            "updateTime": "1775440665000",
            "productionState": "400",
            "priority": "3",
            "livenessTime": "1775440665000",
            "customProperties": null
        }
        ],
        "response": [
        {
            "standard": {
            "id": "AAAAAzxIDQsTlnweGQ04by62PDA=",
            "factIds": [],
            "schemaIds": [
                "Base.Device"
            ],
            "name": "10.88.122.130",
            "timestamp": "1775440665000",
            "tenant": "svc",
            "fields": null,
            "dimensions": {
                "contextUUID": "672267b5-d86a-4600-b96f-97cfc0a7997a",
                "source": "cz0"
            },
            "coreProperties": {
                "HWManufacturer": [
                "VMware, Inc."
                ],
                "HWModel": [
                "VMware Virtual Platform"
                ],
                "HWSerialNumber": [
                "00376-30000-00299-AA408"
                ],
                "HWTag": [
                "System Enclosure 0"
                ],
                "OSManufacturer": [
                "Microsoft Corporation"
                ],
                "OSModel": [
                "Windows Server 2016 Standard"
                ],
                "_zen_direct_entity_id": [
                "AAAAAzxIDQsTlnweGQ04by62PDA="
                ],
                "_zen_impactedEntities": [
                "AAAAA-H8aY6Ii7eeXv2bcbb8HGY=",
                "AAAAA-maSR2oySfT79lSWYgKFi4=",
                "AAAAA0SgtV8XWS_-aoCLuH6QUlY=",
                "AAAAA1O0v211bKH38ttlg76vesI=",
                "AAAAA1xRi1M670LmjiG_4xCznlQ=",
                "AAAAA2tKhBdYxIOAKnFywb-wBXY=",
                "AAAAA3UEOvORDWGyMFgq5f21c_w=",
                "AAAAA3ZffC58Bkj8l7XDP8dYmdU=",
                "AAAAA3t3fwgIz3g6eVZt9DsI4MI=",
                "AAAAA45Ov77K58ugWQKzX_0hQ8k=",
                "AAAAA4MWJPjciJpxPDsfMk8YNgg=",
                "AAAAA50ozsZyj3KahqL8O_heMtA=",
                "AAAAA9hTin5YMA5Tjin8V_XXLSk=",
                "AAAAA_eyR6MJFRd_bA1D5ksk9kw=",
                "AAAAA_jsDndSqMQmcv3M4hrSEVc=",
                "AAAAAwy65UsQ5giiBHCifRc4M5Q=",
                "AAAAAx333V2kevTC38BS2cAdHjs="
                ],
                "_zen_parent_entity_id": [
                "AAAAA-H8aY6Ii7eeXv2bcbb8HGY="
                ],
                "_zen_schemaIds": [
                "Base.Device"
                ],
                "_zen_tenant_id": [
                "dwgywhbbjomrhbtg"
                ],
                "_zorgs_device_class": [
                "/Server/Microsoft/Cluster/ZenossQA"
                ],
                "_zorgs_groups": [
                "/moreThan40"
                ],
                "contextUUID": [
                "672267b5-d86a-4600-b96f-97cfc0a7997a"
                ],
                "device": [
                "10.88.122.130"
                ],
                "name": [
                "10.88.122.130"
                ],
                "parent": [
                "06f442aa-73de-4571-b0ab-8b82631b0585"
                ],
                "source": [
                "cz0"
                ],
                "source-type": [
                "cz"
                ]
            },
            "createTime": "1713148087000",
            "updateTime": "1775440665000",
            "productionState": "400",
            "priority": "3",
            "livenessTime": "1775440665000",
            "customProperties": null
            }
        }
        ]
    },
    "pageInfo": {
        "startCursor": "8iS2WCwiNfapPB8V7YxFnA==",
        "endCursor": "BXouZzSn_NqHf3kCi3P0AA==",
        "count": "1",
        "totalCount": "1",
        "hasNext": false,
        "hasPrev": false,
        "pending": "PENDING_FALSE"
    }
    }