Custom properties resources

The Custom Properties API allows you to manage custom metadata for entities in Virtana Service Observability. Use this service to set properties directly on entities or create automated updaters that continuously apply properties based on entity queries.

Resource list

Set custom properties (POST /v1/modelcontext/customproperties:set)
Delete custom properties (POST /v1/modelcontext/customproperties:delete)
Create custom property updaters (POST /v1/modelcontext/custompropertyupdaters:create)
Update custom property updaters (POST /v1/modelcontext/custompropertyupdaters:change)
Delete custom property updaters (POST /v1/modelcontext/custompropertyupdaters:delete)
List custom property updaters (POST /v1/modelcontext/custompropertyupdaters:list)
Manage custom property updaters (POST /v1/modelcontext/custompropertyupdaters:manage)

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.

Set custom properties for entities

POST /v1/modelcontext/customproperties:set

Set custom properties for entities. This operation adds properties that are not present and replaces values for properties that already exist.

Request template

JSON request to set custom properties on entities:

{
  "input": {
    "with_ids": {
      "ids": ["<entity-id>"]
    }
  },
  "properties": {
    "<property-name>": "<property-value>"
  }
}

{
  "input": {
    "query": {
      "clause": {
        "filter": {
          "field": "<field-name>",
          "operation": "OP_EQUALS",
          "value": "<value>"
        }
      }
    }
  },
  "properties": {
    "<property-name>": "<property-value>"
  }
}

Request fields

Field	Type	Required	Description
`input`	Object	Yes	Entity selection criteria. Use either `with_ids` or `query`.
`input.with_ids`	Object	No	Specify entities by ID list.
`input.with_ids.ids`	Array	Yes	Array of entity IDs.
`input.query`	Object	No	Specify entities using search criteria. See query documentation for query structure details.
`properties`	Object	Yes	Map of property names to values. Property values can be strings, numbers, booleans, or arrays.

Response fields

Field	Description
`entity_ids`	Array of entity IDs that were updated with the custom properties.

Status codes

Code	Description
200	Properties were set successfully.
400	Invalid request — missing input or properties.
401	Authentication required.
403	Insufficient permissions.
500	Internal server error.

Example

Request example

 curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/customproperties:set \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "input": {
    "with_ids": {
      "ids": ["entity_123", "entity_456"]
    }
  },
  "properties": {
    "environment": "production",
    "cost_center": "engineering",
    "priority_level": 3
  }
}'

Response example

 {
  "entity_ids": ["entity_123", "entity_456"]
}

Delete custom properties from entities

POST /v1/modelcontext/customproperties:delete

Delete specified custom properties from entities. If no property keys are specified, all custom properties will be deleted for the selected entities.

Request template

JSON request to delete custom properties:

{
  "input": {
    "with_ids": {
      "ids": ["<entity-id>"]
    }
  },
  "property_keys": ["<property-name>"]
}

Request fields

Field	Type	Required	Description
`input`	Object	Yes	Entity selection criteria. Use either `with_ids` or `query` (same format as set operation).
`property_keys`	Array	No	Array of property names to delete. If omitted, all custom properties are deleted for the selected entities.

Status codes

Code	Description
200	Properties were deleted successfully.
400	Invalid request.
401	Authentication required.
403	Insufficient permissions.
500	Internal server error.

Example

Request example

 curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/customproperties:delete \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "input": {
    "with_ids": {
      "ids": ["entity_123"]
    }
  },
  "property_keys": ["cost_center", "priority_level"]
}'

Response example

{}

Create custom property updaters

POST /v1/modelcontext/custompropertyupdaters:create

Create one or more custom property updaters that automatically apply properties to entities matching specified queries.

Request template

JSON request to create custom property updaters:

{
  "updaters": [
    {
      "name": "<unique-name>",
      "description": "<description>",
      "entity_input": {
        "clause": {
          "filter": {
            "field": "entity.<field-name>",
            "operation": "OP_EQUALS",
            "value": "<value>"
          }
        }
      },
      "properties": {
        "<property-name>": "<property-value>"
      },
      "enabled": true,
      "sequence": 1,
      "tags": ["<tag>"]
    }
  ]
}

Request fields

Field	Type	Required	Description
`updaters`	Array	Yes	Array of custom property updater definitions.
`updaters.name`	String	Yes	Unique name for the updater.
`updaters.description`	String	No	Description of the updater's purpose.
`updaters.entity_input`	Object	Yes	Query defining which entities this updater applies to.
`updaters.properties`	Object	Yes	Map of property names to values that will be applied to matching entities.
`updaters.enabled`	Boolean	No	Whether the updater is active. Default = false.
`updaters.sequence`	Integer	No	Execution order when multiple updaters match the same entity. Default = 0.
`updaters.tags`	Array	No	Array of tags for organization and filtering.

Response fields

Field	Description
`results`	Array of results for each updater creation attempt.
`results.id`	Unique ID of the created updater (if successful).
`results.error`	Error message if creation failed.

Status codes

Code	Description
200	Updaters processed — check individual results for success or failure.
400	Invalid request format.
401	Authentication required.
403	Insufficient permissions.
500	Internal server error.

Example

Request example

 curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/custompropertyupdaters:create \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "updaters": [
    {
      "name": "production_environment_tagger",
      "description": "Tag all production environment entities",
      "entity_input": {
        "clause": {
          "filter": {
            "field": "entity.source",
            "operation": "OP_CONTAINS",
            "value": "prod"
          }
        }
      },
      "properties": {
        "environment": "production",
        "monitoring_level": "critical"
      },
      "enabled": true,
      "sequence": 1,
      "tags": ["environment", "automation"]
    }
  ]
}'

Response example

 {
  "results": [
    {
      "id": "updater789abc",
      "error": ""
    }
  ]
}

Update custom property updaters

POST /v1/modelcontext/custompropertyupdaters:change

Update existing custom property updaters. All fields must be provided as the request replaces the entire updater configuration.

Request template

JSON request to update custom property updaters:

{
  "updaters": [
    {
      "id": "<updater-id>",
      "name": "<name>",
      "description": "<description>",
      "entity_input": {
        "clause": {
          "filter": {
            "field": "entity.<field-name>",
            "operation": "OP_EQUALS",
            "value": "<value>"
          }
        }
      },
      "properties": {
        "<property-name>": "<property-value>"
      },
      "enabled": true,
      "sequence": 1,
      "tags": ["<tag>"]
    }
  ]
}

Request fields

Field	Type	Required	Description
`updaters`	Array	Yes	Array of updater configurations to update.
`updaters.id`	String	Yes	ID of the existing updater to modify.
`updaters.*`	-	Yes	All other fields are the same as create operation and are required.

Response fields

Field	Description
`results`	Array of results for each updater creation attempt.
`results.id`	Unique ID of the created updater (if successful).
`results.error`	Error message if creation failed.

Status codes

Code	Description
200	Updaters processed — check individual results for success or failure.
400	Invalid request format.
401	Authentication required.
403	Insufficient permissions.
500	Internal server error.

Example

Request example

 curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/custompropertyupdaters:change \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "updaters": [
    {
      "id": "updater789abc",
      "name": "production_environment_tagger",
      "description": "Updated: Tag all production environment entities with enhanced monitoring",
      "entity_input": {
        "clause": {
          "filter": {
            "field": "entity.source",
            "operation": "OP_CONTAINS",
            "value": "prod"
          }
        }
      },
      "properties": {
        "environment": "production",
        "monitoring_level": "critical",
        "backup_required": true
      },
      "enabled": true,
      "sequence": 1,
      "tags": ["environment", "automation", "enhanced"]
    }
  ]
}'

Response example

 {
  "results": [
    {
      "id": "updater789abc",
      "error": ""
    }
  ]
}

Delete custom property updaters

POST /v1/modelcontext/custompropertyupdaters:delete

Delete one or more custom property updaters by their IDs.

Request template

JSON request to delete custom property updaters:

{
  "ids": ["<updater-id>"]
}

Request fields

Field	Type	Required	Description
`ids`	Array	Yes	Array of updater IDs to delete.

Response fields

Field	Description
`results`	Array of results for each deletion attempt.
`results.id`	ID of the updater that was processed.
`results.error`	Error message if deletion failed.

Status codes

Code	Description
200	Deletions processed — check individual results for success or failure.
400	Invalid request format.
401	Authentication required.
403	Insufficient permissions.
500	Internal server error.

Example

Request example

 curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/custompropertyupdaters:delete \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "ids": ["updater789abc", "updaterdef456"]
}'

Response example

 {
  "results": [
    {
      "id": "updater789abc",
      "error": ""
    },
    {
      "id": "updaterdef456",
      "error": ""
    }
  ]
}

List custom property updaters

POST /v1/modelcontext/custompropertyupdaters:list

List custom property updaters for the tenant with optional pagination.

Request template

JSON request to list custom property updaters:

{
  "page_input": {
    "limit": 10,
    "cursor": "<cursor-value>"
  }
}

Request fields

Field	Type	Required	Description
`page_input`	Object	No	Pagination parameters.
`page_input.limit`	Integer	No	Maximum number of updaters to return. Default = 50.
`page_input.cursor`	String	No	Pagination cursor for retrieving next page.

Response fields

Field	Description
`updaters`	Array of custom property updater objects.
`updaters.id`	Unique ID of the updater.
`updaters.name`	Name of the updater.
`updaters.description`	Description of the updater.
`updaters.entity_input`	Query defining which entities this updater applies to.
`updaters.properties`	Properties applied by this updater.
`updaters.enabled`	Whether the updater is active.
`updaters.sequence`	Execution sequence number.
`updaters.tags`	Array of tags associated with the updater.
`page_info`	Pagination information.
`page_info.has_next`	Whether there are more results available.
`page_info.cursor`	Cursor for the next page of results.

Status codes

Code	Description
200	List retrieved successfully.
400	Invalid request format.
401	Authentication required.
500	Internal server error.

Example

Request example

 curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/custompropertyupdaters:list \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "page_input": {
    "limit": 5
  }
}'

Response example

 {
  "updaters": [
    {
      "id": "updater789abc",
      "name": "production_environment_tagger",
      "description": "Tag all production environment entities",
      "entity_input": {
        "clause": {
          "filter": {
            "field": "entity.source",
            "operation": "OP_CONTAINS",
            "value": "prod"
          }
        }
      },
      "properties": {
        "environment": "production",
        "monitoring_level": "critical"
      },
      "enabled": true,
      "sequence": 1,
      "tags": ["environment", "automation"]
    }
  ],
  "page_info": {
    "has_next": false,
    "cursor": ""
  }
}

Manage custom property updaters

POST /v1/modelcontext/custompropertyupdaters:manage

Enable or disable existing custom property updaters. Additional action options can be added later.

Request template

JSON request to manage custom property updaters:

{
  "ids": ["<updater-id>"],
  "action": "ENABLE"
}

Request fields

Field	Type	Required	Description
`ids`	Array	Yes	Array of updater IDs to manage.
`action`	String	Yes	Action to perform. Must be either `ENABLE` or `DISABLE`.

Response fields

Field	Description
`results`	Array of results for each management operation.
`results.id`	ID of the updater that was processed.
`results.error`	Error message if operation failed.

Status codes

Code	Description
200	Operations processed — check individual results for success or failure.
400	Invalid request format or action.
401	Authentication required.
403	Insufficient permissions.
500	Internal server error.

Example

Request example

 curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/custompropertyupdaters:manage \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "ids": ["updater789abc"],
  "action": "DISABLE"
}'

Response example

 {
  "results": [
    {
      "id": "updater789abc",
      "error": ""
    }
  ]
}

In this section:

Custom properties resources

Resource list

Authentication

Set custom properties for entities

Request template

Request fields

Response fields

Status codes

Example

Delete custom properties from entities

Request template

Request fields

Status codes

Example

Create custom property updaters

Request template

Request fields

Response fields

Status codes

Example

Update custom property updaters

Request template

Request fields

Response fields

Status codes

Example

Delete custom property updaters

Request template

Request fields

Response fields

Status codes

Example

List custom property updaters

Request template

Request fields

Response fields

Status codes

Example

Manage custom property updaters

Request template

Request fields

Response fields

Status codes

Example

Search results