Skip to main content

Entities resources

The Entities API lets you search for the entities and devices in your Virtana Service Observability tenant, and list the entity fields that are available to search on.

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.

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.

Search entities

POST /v1/modelcontext/entities:search

Searches for devices by the criteria you specify.

  • search_input: Required. Provides the query, sort_by options, page_input options, and group_by options.

  • fields: Optional. Specifies which fields are returned for the matching entities. If you omit this, the default well-known fields are returned.

Request template

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": "192.0.2.10",
                "operation": 1
              }
            },
            {
              "in": {
                "field": "schemaIds",
                "values": [
                  "Base.Device"
                ]
              }
            }
          ]
        }
      }
    }
  }
}

Request fields

Field

Type

Required

Description

search_input

object

Yes

The search criteria, in query format.

search_input.query

object

Yes

Specifies the entities to match, using search criteria.

search_input.page_input

object

No

Page selection criteria.

search_input.page_input.limit

number

No

The maximum number of results to return.

search_input.page_input.cursor

string

No

The endCursor value from a previous page result. Use this to retrieve the next page.

Response fields

Field

Description

entities

An array of entity objects that match the search criteria for the tenant.

pageInfo

Pagination details, including startCursor and endCursor. Use endCursor to retrieve remaining entities.

Response codes

Code

Description

200

Successful.

400

Invalid request. For example, the search input was empty.

500

Internal server error.

Examples

Request 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": "192.0.2.10",
                        "operation": 1
                    }
                    },
                    {
                    "in": {
                        "field": "schemaIds",
                        "values": [
                        "Base.Device"
                        ]
                    }
                    }
                ]
                }
            }
        }
    }
}'

Response example

{
    "entities": {
        "entities": [
        {
            "id": "AAAAAzxIDQsTlnweGQ04by62PDA=",
            "factIds": [],
            "schemaIds": [
            "Base.Device"
            ],
            "name": "192.0.2.10",
            "timestamp": "1775440665000",
            "tenant": "<tenant name>",
            "fields": null,
            "dimensions": {
            "contextUUID": "672267b5-d86a-4600-b96f-97cfc0a7997a",
            "source": "cz0"
            },
            "coreProperties": {
            "HWManufacturer": [
                "VMware, Inc."
            ],
            "HWModel": [
                "VMware Virtual Platform"
            ],
            "HWSerialNumber": [
                "<serial number>"
            ],
            "HWTag": [
                "System Enclosure 0"
            ],
            "OSManufacturer": [
                "Microsoft Corporation"
            ],
            "OSModel": [
                "Windows Server 2016 Standard"
            ],
            "_zen_direct_entity_id": [
                "AAAAAzxIDQsTlnweGQ04by62PDA="
            ],
            "_zen_parent_entity_id": [
                "AAAAA-H8aY6Ii7eeXv2bcbb8HGY="
            ],
            "_zen_schemaIds": [
                "Base.Device"
            ],
            "_zen_tenant_id": [
                "<tenant id>"
            ],
            "_zorgs_device_class": [
                "/Server/Microsoft/Cluster/Example"
            ],
            "_zorgs_groups": [
                "/ExampleGroup"
            ],
            "contextUUID": [
                "672267b5-d86a-4600-b96f-97cfc0a7997a"
            ],
            "device": [
                "192.0.2.10"
            ],
            "name": [
                "192.0.2.10"
            ],
            "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"
    }
}

List default fields and field sources

POST /v1/modelcontext/fields:listDefault

Returns the default fields and field sources for your tenant. Use the request parameters to filter by field type, core or all, and by whether fields must be searchable through the API.

Request template

The JSON request used to list default fields and field sources:

{
  "option": <0 or 1>,
  "searchable_only": <true or false>
}

Request fields

Field

Type

Required

Description

option

number

No

Specify 0 to list only core fields. Specify 1 to list all fields. Default: 0.

searchable_only

boolean

No

Specify true to list only the fields that can be searched through the API.

Response fields

Field

Description

fields

An array of field keys on the tenant's entities that match the request parameters.

fieldSources

The source classification for each field key. Search property keys directly, prefix coreProperty keys with coreProperties., and prefix dimension keys with dimensions.

Response codes

Code

Description

200

Successful.

500

Internal server error.

Examples

Request example

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/fields:listDefault \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
    "option": 0,
    "searchable_only":true
}'

Response example

{
    "fields": [
        "HWManufacturer",
        "HWModel",
        "HWSerialNumber",
        "HWTag",
        "OSManufacturer",
        "OSModel",
        "_zen_parent_entity_id",
        "_zen_schemaIds",
        "_zorgs_component_groups",
        "_zorgs_device_class",
        "_zorgs_groups",
        "_zorgs_impact_ds_organizer",
        "_zorgs_location",
        "_zorgs_systems",
        "device",
        "name",
        "source",
        "source-type"
    ],
    "fieldSources": {
        "HWManufacturer": "coreProperty",
        "HWModel": "coreProperty",
        "HWSerialNumber": "coreProperty",
        "HWTag": "coreProperty",
        "OSManufacturer": "coreProperty",
        "OSModel": "coreProperty",
        "_zen_clientid": "coreProperty",
        "_zen_direct_entity_id": "coreProperty",
        "_zen_impactedBy": "coreProperty",
        "_zen_impactedEntities": "coreProperty",
        "_zen_parent_entity_id": "coreProperty",
        "_zen_schemaIds": "coreProperty",
        "_zen_tenant_id": "coreProperty",
        "_zorgs_component_groups": "coreProperty",
        "_zorgs_device_class": "coreProperty",
        "_zorgs_groups": "coreProperty",
        "_zorgs_impact_ds_organizer": "coreProperty",
        "_zorgs_location": "coreProperty",
        "_zorgs_systems": "coreProperty",
        "contextUUID": "coreProperty",
        "device": "coreProperty",
        "name": "coreProperty",
        "parent": "coreProperty",
        "source": "coreProperty",
        "source-type": "coreProperty"
    }
}
In this section: