Maintenance Windows resources

The Maintenance Windows API lets you manage maintenance window configurations for entities in Virtana Service Observability. Use this service to create, edit, list, search, or delete maintenance windows based on entity queries.

Resource list

Create a maintenance window (Create a maintenance window)
Update a maintenance window (Update a maintenance window)
List maintenance windows (List maintenance windows)
Search maintenance windows (Search maintenance windows)
Delete maintenance windows (Delete maintenance windows)

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.

Create a maintenance window

POST /v1/modelcontext/maintwindows

Creates a maintenance window (MW) configuration for one or more devices. Specify the target devices either by their unique entity IDs (withIds) or with an entity query. A typical entity query specifies criteria such as the device's schema ID (for example, Base.Device), the Collection Zone (CZ) it belongs to, and a field for identification, such as coreProperties.name, coreProperties.device, or an organizer such as coreProperties._zorgs_device_class or coreProperties._zorgs_groups.

The response returns the unique ID of the created MW.

Request templates

JSON request used to create an MW that targets entities by ID:

{
  "specification": {
    "schedule": {
      "start": <timestamp in milliseconds>,
      "duration": <duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": <300>,
    "exitState": <1000>,
    "runMode": 0,
    "status": 0,
    "name": "<name>",
    "overrideExitState": false,
    "force": true,
    "description": "<description>",
    "doNotPropagateToChildren": false,
    "withIds": {
      "ids": [
        "<entityID1>"
      ]
    }
  }
}

Alternatively, target entities with a query instead of a list of IDs:

{
  "specification": {
    "schedule": {
      "start": <timestamp in milliseconds>,
      "duration": <duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": <300>,
    "exitState": <1000>,
    "runMode": 0,
    "status": 0,
    "name": "<unique name>",
    "overrideExitState": false,
    "force": true,
    "description": "<optional description>",
    "doNotPropagateToChildren": false,
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "coreProperties.name",
                "value": "<name>",
                "operation": 1
              }
            },
            {
              "in": {
                "field": "schemaIds",
                "values": [
                  "Base.Device"
                ]
              }
            }
          ]
        }
      }
    }
  }
}

To recur weekly on a specific day, set recurrence.type to 4 and include dayOfWeek:

"recurrence": {
  "dayOfWeek": "3",
  "interval": 1,
  "type": 4
}

To recur daily, set recurrence.type to 3:

"recurrence": {
  "interval": 1,
  "type": 3
}

Request fields

Field	Type	Required	Description
`specification`	object	Yes	The maintenance window configuration to create.
`specification.name`	string	Yes	A unique identifier for the MW. This value must be unique across your tenant.
`specification.schedule`	object	Yes	The schedule that determines when the MW runs.
`specification.schedule.start`	number	Yes	When the MW starts running, in milliseconds since the epoch.
`specification.schedule.duration`	number	Yes	How long the MW runs, in milliseconds.
`specification.schedule.recurrence`	object	Yes	Determines whether and how the MW repeats. Set to `null` for no recurrence. This setting is for advanced users; see the weekly and daily recurrence examples above.
`specification.schedule.recurrence.interval`	number	No	The interval for the recurrence. Required for most recurrence types.
`specification.schedule.recurrence.dayOfWeek`	string	No	The day of the week for a weekly recurrence. Required when `type` is `4` (weekly).
`specification.schedule.recurrence.dayOfMonth`	string	No	The day of the month for a monthly recurrence. Required when `type` is `5` (monthly).
`specification.schedule.recurrence.minutes`	string	No	The minutes value for a cron-based recurrence.
`specification.schedule.recurrence.hours`	string	No	The hours value for a cron-based recurrence.
`specification.schedule.recurrence.month`	string	No	The month value for a cron-based recurrence.
`specification.schedule.recurrence.year`	string	No	The year value for an extended cron-based recurrence.
`specification.schedule.recurrence.type`	number	No	The recurrence type. Accepted values: `0`: `MW_RECURRENCE_CUSTOM`. Custom frequency based on time. Uses `interval`, interpreted as milliseconds. `1`: `MW_RECURRENCE_CRON`. Standard cron specification. Uses all recurrence fields except `year` and `interval`. `2`: `MW_RECURRENCE_CRON_ADVANCED`. Extended cron specification (standard plus `L`, `#`, and `year`). Uses all recurrence fields except `interval`. `3`: `MW_RECURRENCE_DAILY`. Occurs every `n` days. Uses `interval`. `4`: `MW_RECURRENCE_WEEKLY`. Occurs on specific days of the week. Uses `interval` and `dayOfWeek`. `5`: `MW_RECURRENCE_MONTHLY`. Occurs on specific days of the month. Uses `interval` and `dayOfMonth`.
`specification.maintenanceState`	number	Yes	The production state that entities are set to during the MW.
`specification.exitState`	number	No	The production state that entities are set to after the MW ends. Used together with `overrideExitState`.
`specification.runMode`	number	No	How the MW runs. Default: `0`. Accepted values: `0`: `AUTO`. `1`: `Manual`.
`specification.status`	number	No	The MW's enabled state. Default: `0`. Accepted values: `0`: Enabled. `1`: Disabled.
`specification.withIds`	object	No	Specifies target entities by ID. Use instead of `query` if you already know the entity IDs.
`specification.withIds.ids`	array	Yes	An array of entity IDs. Required when `withIds` is included.
`specification.query`	object	No	Specifies target entities using search criteria. Use instead of `withIds` if you don't know the entity IDs.
`specification.description`	string	No	A description of the MW configuration.
`specification.owner`	string	No	The owner of the MW configuration.
`specification.overrideExitState`	boolean	No	When `true`, sets the production state of the target entities to `exitState` when the MW ends. Default: `false`.
`specification.force`	boolean	No	Advanced use. When `true`, overrides checks that prevent creating MWs with the same entities on the same schedule. Default: `false`.
`specification.doNotPropagateToChildren`	boolean	No	Advanced use. When `true`, child entities of the target device entities don't have their production state set to `maintenanceState` during the MW run. Default: `false`.
`specification.tags`	array	No	An array of string tags.
`specification.notification`	object	No	A notification message and rules used by the Actions framework.

Request codes

Code	Description
200	Created. The MW configuration was created successfully.
400	Invalid request. For example, the MW name was repeated.
500	Internal server error.

Examples

Request example

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/maintwindows \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
    "specification": {
    "schedule": {
      "start": <start in milliseconds>,
      "duration": <duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": 300,
    "name": "<unique mw name>",
    "description": "<mw description>",
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "coreProperties.name",
                "value": "<device name>",
                "operation": 1
              }
            },
            {
              "in": {
                "field": "schemaIds",
                "values": [
                  "Base.Device"
                ]
              }
            }
          ]
        }
      }
    }
  }  
}'

Response example

{
  "id": "mw_id"
}

Update a maintenance window

PUT /v1/modelcontext/maintwindows

Updates an existing maintenance window (MW) configuration. The request body must match the original creation schema and include every field, not just the fields you want to change; partial updates aren't supported. The name field is immutable and can't be changed.

Request template

An abstract preview of a JSON request used to update an MW that targets entities by ID:

{
  "id": "<id of the MW to edit>",
  "specification": {
    "schedule": {
      "start": <timestamp in milliseconds>,
      "duration": <duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": <300>,
    "exitState": <1000>,
    "runMode": 0,
    "status": 0,
    "name": "<name>",
    "overrideExitState": false,
    "force": true,
    "description": "<description>",
    "doNotPropagateToChildren": false,
    "withIds": {
      "ids": [
        "<entityID1>"
      ]
    }
  }
}

Alternatively, target entities with a query instead of a list of IDs:

{
  "id": "<id of the MW to edit>",
  "specification": {
    "schedule": {
      "start": <timestamp in milliseconds>,
      "duration": <duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": <300>,
    "exitState": <1000>,
    "runMode": 0,
    "status": 0,
    "name": "<unique name>",
    "overrideExitState": false,
    "force": true,
    "description": "<optional description>",
    "doNotPropagateToChildren": false,
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "coreProperties.name",
                "value": "<name>",
                "operation": 1
              }
            },
            {
              "in": {
                "field": "schemaIds",
                "values": [
                  "Base.Device"
                ]
              }
            }
          ]
        }
      }
    }
  }
}

Request fields

Field	Type	Required	Description
`id`	string	Yes	The ID of the MW to update.
`specification`	object	Yes	The full MW configuration, including every field used at creation. The `name` field is immutable and can't be changed.

See Create a maintenance window for a full description of each specification field. All fields carry the same meaning here; they must all be resubmitted on every update.

Response codes

Code	Description
200	Successful. The MW configuration was updated.
400	Invalid request. For example, an attempt to update the `name` field.
404	Not found. For example, no MW exists for the provided `id`.
500	Internal server error.

Examples

Request example

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/maintwindows \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X PUT -s \
  -d '{
    "id":"<mw id to modify>",
    "specification": {
    "schedule": {
      "start": <start in milliseconds>,
      "duration": <duration in milliseconds>,
      "recurrence": null
    },
    "maintenanceState": 300,
    "name": "unique mw name of mw from id",
    "description": "<modified mw description>",
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "coreProperties.name",
                "value": "<device name>",
                "operation": 1
              }
            },
            {
              "in": {
                "field": "schemaIds",
                "values": [
                  "Base.Device"
                ]
              }
            }
          ]
        }
      }
    }
  }
}'

Response example

{}

List maintenance windows

POST /v1/modelcontext/maintwindows:list

Returns a list of maintenance window (MW) specifications configured for your tenant. This endpoint supports paging: specify the number of MWs to return per page, then use the returned cursor to retrieve subsequent pages.

Request template

A simplified JSON request that retrieves the first page of MWs:

{
  "page_input": {
    "limit": 10
  }
}

To retrieve a subsequent page, pass the cursor from the previous response:

{
  "page_input": {
    "limit": 10,
    "cursor": "<endCursor from previous page result>"
  }
}

Request fields

Field	Type	Required	Description
`page_input`	object	Yes	Page selection criteria.
`page_input.limit`	number	No	The maximum number of MWs to return per page.
`page_input.cursor`	string	No	The `endCursor` value from a previous page result. Use this to retrieve the next page.

Response fields

Field	Description
`maintWindows`	An array of MW configuration objects created for the tenant. Each object includes the specification fields plus housekeeping fields such as `createdBy`, `updatedBy`, and `deleted`.
`pageInfo`	Pagination details, including `startCursor` and `endCursor`. Use `endCursor` to retrieve remaining MWs.

Response codes

Code	Description
200	Successful.
500	Internal server error.

Examples

Request example

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

Response example

{
  "maintWindows": [
    {
      "id": "<mw id>",
      "tenant": "<tenant name>",
      "query": {
        "type": "RESULT_TYPE_ENTITY",
        "timeRange": null,
        "clause": {
          "and": {
            "clauses": [
              {
                "filter": {
                  "field": "schemaIds",
                  "operation": "OP_CONTAINS",
                  "value": "Base.Device",
                  "options": []
                }
              },
              {
                "filter": {
                  "field": "name",
                  "operation": "OP_EQUALS",
                  "value": "pfg-windows-mssql",
                  "options": []
                }
              }
            ]
          }
        }
      },
      "runMode": "MANUAL",
      "schedule": {
        "start": "0",
        "duration": "600000",
        "skipNext": "0",
        "recurrence": null
      },
      "maintenanceState": "300",
      "exitState": "1000",
      "status": "ENABLED",
      "createTime": "1775526877007",
      "updateTime": "1775526877007",
      "deleted": false,
      "createdBy": "user@example.com",
      "updatedBy": "user@example.com",
      "name": "testInClause",
      "description": "",
      "owner": "",
      "notification": {
        "message": "",
        "rules": []
      },
      "tags": [],
      "doNotPropagateToChildren": false,
      "overrideExitState": false,
      "force": false
    }
  ],
  "pageInfo": {
    "startCursor": "",
    "endCursor": "fNybM12dj1zRmkLdQq8Ovw==",
    "count": "1",
    "totalCount": "1466",
    "hasNext": true,
    "hasPrev": false,
    "pending": "PENDING_FALSE"
  }
}

Search maintenance windows

POST /v1/modelcontext/maintwindows:search

Searches for maintenance windows (MWs) that match the filters you specify. This endpoint requires familiarity with the query v2 syntax; for example, you can search for all MWs with run_mode: manual. See Trigger queries for more on query syntax.

Request template

An abstract preview of a JSON request used to search for an MW with a unique name:

{
  "search_input": {
    "page_input": {
      "limit": 10
    },
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "name",
                "value": "testMwById",
                "operation": 1
              }
            }
          ]
        }
      }
    }
  }
}

Request fields

Field	Type	Required	Description
`search_input`	object	Yes	The search criteria, in query format.
`search_input.query`	object	Yes	The query that defines which MWs the search applies to.
`search_input.page_input`	object	No	Pagination input for the request.
`search_input.page_input.limit`	number	No	The maximum number of MWs to return. Required when `page_input` is included.

Response fields

Field	Description
`maintWindows`	An array of MW configuration objects that match the search criteria. Each object includes the specification fields plus housekeeping fields such as `createdBy`, `updatedBy`, and `deleted`.
`pageInfo`	Pagination details, including `startCursor` and `endCursor`. Use `endCursor` to retrieve remaining MWs.

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/maintwindows:search \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
    "search_input": {
    "page_input": {
      "limit": 1
    },
    "query": {
      "clause": {
        "and": {
          "clauses": [
            {
              "filter": {
                "field": "name",
                "value": "testMwByQuery",
                "operation": 1
              }
            }
          ]
        }
      }
    }
  }
}'

Response example

{
  "maintWindows": [
    {
      "id": "99fa4d8b-3223-11f1-8920-625b6e77d030",
      "tenant": "<tenant>",
      "query": {
        "type": "RESULT_TYPE_ENTITY",
        "timeRange": null,
        "clause": {
          "and": {
            "clauses": [
              {
                "filter": {
                  "field": "coreProperties.name",
                  "operation": "OP_EQUALS",
                  "value": "pfg-windows-mssql",
                  "options": []
                }
              },
              {
                "in": {
                  "field": "schemaIds",
                  "values": [
                    "Base.Device"
                  ],
                  "options": []
                }
              }
            ]
          }
        }
      },
      "runMode": "AUTO",
      "schedule": {
        "start": "1780775331000",
        "duration": "600000",
        "skipNext": "0",
        "recurrence": null
      },
      "maintenanceState": "300",
      "exitState": "0",
      "status": "ENABLED",
      "createTime": "1775526391375",
      "updateTime": "1775526391375",
      "deleted": false,
      "createdBy": "user@example.com",
      "updatedBy": "user@example.com",
      "name": "testMwByQuery",
      "description": "test mw by entity id",
      "owner": "",
      "notification": null,
      "tags": [],
      "doNotPropagateToChildren": false,
      "overrideExitState": false,
      "force": false
    }
  ],
  "pageInfo": {
    "startCursor": "",
    "endCursor": "pZqj4W2bXosHRgE-UszbIw==",
    "count": "1",
    "totalCount": "7",
    "hasNext": true,
    "hasPrev": false,
    "pending": "PENDING_FALSE"
  }
}

Delete maintenance windows

POST /v1/modelcontext/maintwindows:deleteBulk

Deletes the maintenance windows (MWs) that correspond to the provided list of IDs.

Request template

A sample JSON request body used to delete one or more MWs by ID:

{
  "ids": [
    "<mw id>"
  ]
}

Request fields

Field	Type	Required	Description
`ids`	array	Yes	An array of MW IDs to delete. These are the same IDs returned in the response when the MWs were created.

Response codes

Code	Description
200	Successful.
400	Invalid request. For example, no IDs were provided.
404	Not found. For example, no MW exists for the provided ID.
500	Internal server error.

Examples

Request example

curl https://<YOUR-API-ENDPOINT>/v1/modelcontext/maintwindows:deleteBulk \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
    "ids": [
        "<mw id>"
      ]
}'

Response example

{}

In this section:

Maintenance Windows resources

Resource list

Authentication

Create a maintenance window

Request templates

Request fields

Request codes

Examples

Update a maintenance window

Request template

Request fields

Response codes

Examples

List maintenance windows

Request template

Request fields

Response fields

Response codes

Examples

Search maintenance windows

Request template

Request fields

Response fields

Response codes

Examples

Delete maintenance windows

Request template

Request fields

Response codes

Examples

Search results