Custom properties resources

The Custom Properties API allows you to manage custom metadata for entities in Zenoss Cloud. 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 Zenoss 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 Zenoss 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.

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

An abstract preview of a JSON request to set custom properties on entities.

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

OR

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

Request fields

input (object, required)

Entity selection criteria. Use either with_ids or query.

with_ids (object, optional)

Specify entities by ID list.

ids (array, required)

Array of entity IDs.

query (object, optional)

Specify entities using search criteria. See query documentation for query structure details.

properties (object, required)

Map of property names to values. Property values can be strings, numbers, booleans, or arrays.

Response fields

entity_ids

Array of entity IDs that were updated with the custom properties.

Status codes

• 200 (properties were set successfully)
• 400 (invalid request - missing input or properties)
• 401 (authentication required)
• 403 (insufficient permissions)
• 500 (internal server error)

Example

RequestResponse

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
  }
}'

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

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

An abstract preview of a JSON request to delete custom properties.

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

Request fields

input (object, required)

Entity selection criteria. Use either with_ids or query (same format as set operation).

property_keys (array, optional)

Array of property names to delete. If omitted, all custom properties are deleted for the selected entities.

Status codes

• 200 (properties were deleted successfully)
• 400 (invalid request)
• 401 (authentication required)
• 403 (insufficient permissions)
• 500 (internal server error)

Example

RequestResponse

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"]
}'

{}

POST /v1/modelcontext/custompropertyupdaters:create

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

Request template

An abstract preview of a 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

updaters (array, required)

Array of custom property updater definitions.

name (string, required)

Unique name for the updater.

description (string, optional)

Description of the updater's purpose.

entity_input (object, required)

Query defining which entities this updater applies to.

properties (object, required)

Map of property names to values that will be applied to matching entities.

enabled (boolean, optional, default = false)

Whether the updater is active.

sequence (integer, optional, default = 0)

Execution order when multiple updaters match the same entity.

tags (array, optional)

Array of tags for organization and filtering.

Response fields

results

Array of results for each updater creation attempt.

id

Unique ID of the created updater (if successful).

error

Error message if creation failed.

Status codes

• 200 (updaters processed - check individual results for success/failure)
• 400 (invalid request format)
• 401 (authentication required)
• 403 (insufficient permissions)
• 500 (internal server error)

Example

RequestResponse

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"]
    }
  ]
}'

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

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

An abstract preview of a 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

updaters (array, required)

Array of updater configurations to update.

id (string, required)

ID of the existing updater to modify.

All other fields are the same as create operation and are required.

Response fields

Same format as create operation.

Status codes

Same as create operation.

Example

RequestResponse

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"]
    }
  ]
}'

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

POST /v1/modelcontext/custompropertyupdaters:delete

Delete one or more custom property updaters by their IDs.

Request template

An abstract preview of a JSON request to delete custom property updaters.

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

Request fields

ids (array, required)

Array of updater IDs to delete.

Response fields

results

Array of results for each deletion attempt.

id

ID of the updater that was processed.

error

Error message if deletion failed.

Status codes

• 200 (deletions processed - check individual results for success/failure)
• 400 (invalid request format)
• 401 (authentication required)
• 403 (insufficient permissions)
• 500 (internal server error)

Example

RequestResponse

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

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

POST /v1/modelcontext/custompropertyupdaters:list

List custom property updaters for the tenant with optional pagination.

Request template

An abstract preview of a JSON request to list custom property updaters.

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

Request fields

page_input (object, optional)

Pagination parameters.

limit (integer, optional, default = 50)

Maximum number of updaters to return.

cursor (string, optional)

Pagination cursor for retrieving next page.

Response fields

updaters

Array of custom property updater objects.

id

Unique ID of the updater.

name

Name of the updater.

description

Description of the updater.

entity_input

Query defining which entities this updater applies to.

properties

Properties applied by this updater.

enabled

Whether the updater is active.

sequence

Execution sequence number.

tags

Array of tags associated with the updater.

page_info

Pagination information.

has_next

Whether there are more results available.

cursor

Cursor for the next page of results.

Status codes

• 200 (list retrieved successfully)
• 400 (invalid request format)
• 401 (authentication required)
• 500 (internal server error)

Example

RequestResponse

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

{
  "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": ""
  }
}

POST /v1/modelcontext/custompropertyupdaters:manage

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

Request template

An abstract preview of a JSON request to manage custom property updaters.

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

Request fields

ids (array, required)

Array of updater IDs to manage.

action (string, required)

Action to perform. Must be either ENABLE or DISABLE.

Response fields

results

Array of results for each management operation.

id

ID of the updater that was processed.

error

Error message if operation failed.

Status codes

• 200 (operations processed - check individual results for success/failure)
• 400 (invalid request format or action)
• 401 (authentication required)
• 403 (insufficient permissions)
• 500 (internal server error)

Example

RequestResponse

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

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