--- updatedAt: 2026-09-08T20:26:09.000Z agentTools: projectIndex: https://docs.observeinc.com/llms.txt --- # Update a MonitorV2 Partially updates a monitor. Only **PATCH** is supported for this URL. **Top-level merge:** The server reads the current monitor, then for each of these properties—`name`, `disabled`, `description`, `ruleKind`, `definition`, `actionRules`—uses the request value if the key is present in the body, otherwise keeps the stored value. Keys omitted from the body do not change. **Replace entire subtrees:** If `definition` or `actionRules` appears in the body, it **replaces the whole** stored `definition` or `actionRules` value. The server does **not** deep-merge inside `definition`, inside individual action rules, or inside nested structures (for example an action rule’s `definition`). To change part of the monitor definition or action configuration, send the complete `definition` and/or full `actionRules` array you want saved. **Action rules:** when a rule's `definition.inline` is `true` the action belongs to this monitor, and sending the rule back updates that action in place, keeping its `actionId`. To rotate a PagerDuty `routing_key`, which sits in `definition.webhook.body`, GET the monitor, edit the key, and PATCH `actionRules` back. A rule pointing at a shared action (`definition.inline` is `false`) is bound by `actionId` alone; change a shared action's payload on the action itself. **Not controlled by the body:** Other monitor fields (such as `id` from the path, or `monitorVersion`) are not updated from this JSON body using the merge rules above. **Extra properties:** Any other top-level JSON properties in the body are ignored for this merge (they are not written to the monitor). # OpenAPI definition ````json { "openapi": "3.1.0", "info": { "title": "Observe API", "description": "# Overview\nWelcome to the Observe API Docs!\n\nThe Observe API is a RESTful API. POST bodies and responses are typically JSON-encoded.\n\n## Authentication\nRequests to the Observe API are authenticated with an API token. The token can be supplied using HTTP Bearer authentication:\n```\n// passing token as bearer token\ncurl -H \"Authorization: Bearer \" https://..com/v1/...\n```\n", "version": "1.0.230307" }, "servers": [ { "url": "https://{customerid}.observeinc.com", "description": "US west server", "variables": { "customerid": { "default": "OBSERVE_CUSTOMERID", "description": "The customer ID for your instance." } } }, { "url": "https://{customerid}.{cluster}.observeinc.com", "description": "Specific regional cluster (prod)", "variables": { "customerid": { "default": "OBSERVE_CUSTOMERID", "description": "The customer ID for your instance." }, "cluster": { "enum": [ "eu-1", "ap-1" ], "default": "eu-1", "description": "For regional clusters, choose one." } } }, { "url": "https://{customerid}.{domain}.com", "description": "Specific Observe server", "variables": { "customerid": { "default": "OBSERVE_CUSTOMERID", "description": "The customer ID for your instance." }, "domain": { "default": "OBSERVE_DOMAIN", "description": "The Observe domain for your instance." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Monitor", "description": "Manage monitors. Learn more about [monitors](https://docs.observeinc.com/en/latest/content/monitors/MonitorsIntro.html).\n" } ], "paths": { "/v1/monitors/{id}": { "patch": { "summary": "Update a MonitorV2", "description": "Partially updates a monitor. Only **PATCH** is supported for this URL.\n\n**Top-level merge:** The server reads the current monitor, then for each of these\nproperties—`name`, `disabled`, `description`, `ruleKind`, `definition`, `actionRules`—uses\nthe request value if the key is present in the body, otherwise keeps the stored value.\nKeys omitted from the body do not change.\n\n**Replace entire subtrees:** If `definition` or `actionRules` appears in the body, it\n**replaces the whole** stored `definition` or `actionRules` value. The server does **not**\ndeep-merge inside `definition`, inside individual action rules, or inside nested structures\n(for example an action rule’s `definition`). To change part of the monitor definition or\naction configuration, send the complete `definition` and/or full `actionRules` array you want\nsaved.\n\n**Action rules:** when a rule's `definition.inline` is `true` the action belongs to this\nmonitor, and sending the rule back updates that action in place, keeping its `actionId`.\nTo rotate a PagerDuty `routing_key`, which sits in `definition.webhook.body`, GET the\nmonitor, edit the key, and PATCH `actionRules` back. A rule pointing at a shared action\n(`definition.inline` is `false`) is bound by `actionId` alone; change a shared action's\npayload on the action itself.\n\n**Not controlled by the body:** Other monitor fields (such as `id` from the path, or\n`monitorVersion`) are not updated from this JSON body using the merge rules above.\n\n**Extra properties:** Any other top-level JSON properties in the body are ignored for this\nmerge (they are not written to the monitor).\n", "operationId": "updateMonitor", "tags": [ "Monitor" ], "parameters": [ { "name": "id", "required": true, "schema": { "type": "integer" }, "in": "path", "description": "The Monitor object id" } ], "requestBody": { "description": "Any subset of patchable fields. Omitted keys among\n`name`, `disabled`, `description`, `ruleKind`, `definition`, and `actionRules` leave the\ncorresponding stored values unchanged. When `definition` or `actionRules` is sent, it must\nbe the full replacement value for that field.\n", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorV2PatchRequest" } } } }, "responses": { "204": { "description": "The object was updated\n" }, "400": { "description": "Invalid request" }, "404": { "description": "The object was not found" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Authorization: Bearer \n" } }, "schemas": { "InputDefinition": { "type": "object", "required": [ "inputName" ], "properties": { "inputName": { "description": "The @name used to reference this input in OPAL (without the @ sign)", "type": "string" }, "inputRole": { "description": "Data or Reference, defaults to Data if not specified.", "type": "string" }, "datasetId": { "description": "The dataset ID (as int64-string) to bind to this name.", "type": "string", "format": "int64" }, "datasetPath": { "description": "The dataset name as Workspace.path/Name to bind to this name. datasetId takes precedence if both are set; on read, this is populated alongside datasetId as a portable reference.", "type": "string" }, "stageId": { "description": "The stageID of the previously defined stage to reference, if it's a stage and not a dataset.", "type": "string" }, "parameterId": { "description": "The parameter ID to take the input dataset reference from. (Advanced usage only)", "type": "string" } } }, "ObjectId": { "type": "string", "format": "ObjectId" }, "MonitorV2RuleKind": { "type": "string", "enum": [ "Anomaly", "Count", "Promote", "Threshold" ] }, "StageQuery": { "type": "object", "required": [ "input", "pipeline" ], "properties": { "id": { "type": "string" }, "input": { "$ref": "#/components/schemas/InputDefinition" }, "pipeline": { "type": "string" } } }, "MultiStageQuery": { "type": "object", "required": [ "outputStage", "stages" ], "properties": { "outputStage": { "type": "string" }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/StageQuery" } } } }, "MonitorV2AlarmLevel": { "type": "string", "enum": [ "Critical", "Error", "Informational", "None", "Warning" ] }, "MonitorV2ComparisonFunction": { "type": "string", "enum": [ "Contains", "Equal", "Greater", "GreaterOrEqual", "Less", "LessOrEqual", "NotContains", "NotEqual", "NotStartsWith", "StartsWith" ] }, "TimeNano": { "type": "string", "format": "RFC3339Nano" }, "DurationNanoseconds": { "type": "string", "format": "int64 nanoseconds" }, "PrimitiveValue": { "properties": { "bool": { "type": "boolean" }, "float64": { "type": "number", "format": "double" }, "int64": { "type": "string", "format": "int64" }, "string": { "type": "string" }, "timestamp": { "$ref": "#/components/schemas/TimeNano" }, "duration": { "$ref": "#/components/schemas/DurationNanoseconds" }, "array": { "type": "array", "items": { "$ref": "#/components/schemas/PrimitiveValue" } }, "link": { "type": "object", "properties": { "datasetId": { "$ref": "#/components/schemas/ObjectId" }, "primaryKeyValue": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "storedLabel": { "type": "string" } } }, "datasetref": { "type": "object", "properties": { "datasetId": { "$ref": "#/components/schemas/ObjectId" }, "datasetPath": { "type": "string" }, "stageId": { "type": "string" } } } } }, "MonitorV2Comparison": { "properties": { "compareFn": { "$ref": "#/components/schemas/MonitorV2ComparisonFunction" }, "compareValue": { "$ref": "#/components/schemas/PrimitiveValue" } } }, "MonitorV2ColumnPath": { "properties": { "name": { "type": "string" }, "path": { "type": "string" } } }, "MonitorV2LinkColumn": { "properties": { "name": { "type": "string" }, "meta": { "type": "object", "properties": { "srcFields": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2ColumnPath" } }, "dstFields": { "type": "array", "items": { "type": "string" } }, "targetDataset": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" } } } } } }, "MonitorV2CorrelationTag": { "type": "object", "description": "Marker on a `MonitorV2Column` indicating that the column is grouping by a\ncorrelation tag (e.g. `service.name`) rather than a specific physical\ncolumn. The per-column struct carries the tag name and optional resolution\n`meta`; the authoritative `(tag, backing-column)` mapping for every\ncorrelation tag in the schema lives on `MonitorV2AlertSchema.correlationTags`.\n", "properties": { "tag": { "type": "string", "description": "Correlation tag name, without the leading `#`. The save-time resolver\nexpands this into the canonical primary backing column picked by the\nOPAL coalesce ordering and records the `(tag, column)` pair on\n`MonitorV2AlertSchema.correlationTags`; this column itself carries\nonly the tag identifier.\n" }, "meta": { "type": "object", "description": "Optional resolution context surfaced for frontend preview/display: the\nphysical backing columns the tag resolves to.\n", "properties": { "srcFields": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2ColumnPath" } } } } } }, "MonitorV2Column": { "description": "Identifies a column in a monitor's input pipeline. At most one of\n`linkColumn`, `columnPath`, and `correlationTag` may be set; the\nsave-time validator rejects violations of this one-of contract.\n", "properties": { "linkColumn": { "$ref": "#/components/schemas/MonitorV2LinkColumn" }, "columnPath": { "$ref": "#/components/schemas/MonitorV2ColumnPath" }, "correlationTag": { "$ref": "#/components/schemas/MonitorV2CorrelationTag" } } }, "MonitorV2ColumnComparison": { "properties": { "compareValues": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2Comparison" } }, "column": { "$ref": "#/components/schemas/MonitorV2Column" } } }, "MonitorV2CountRule": { "type": "object", "required": [ "compareValues" ], "properties": { "compareValues": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2Comparison" } }, "compareGroups": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2ColumnComparison" } } } }, "MonitorV2ValueAggregation": { "type": "string", "enum": [ "AllOf", "AnyOf", "AvgOf", "SumOf" ] }, "MonitorV2ThresholdRule": { "type": "object", "required": [ "compareValues", "valueColumnName", "aggregation" ], "properties": { "compareValues": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2Comparison" } }, "valueColumnName": { "type": "string" }, "aggregation": { "$ref": "#/components/schemas/MonitorV2ValueAggregation" }, "compareGroups": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2ColumnComparison" } } } }, "MonitorV2PromoteRule": { "type": "object", "properties": { "compareColumns": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2ColumnComparison" } } } }, "MonitorV2Rule": { "type": "object", "properties": { "level": { "$ref": "#/components/schemas/MonitorV2AlarmLevel" }, "count": { "$ref": "#/components/schemas/MonitorV2CountRule" }, "threshold": { "$ref": "#/components/schemas/MonitorV2ThresholdRule" }, "promote": { "$ref": "#/components/schemas/MonitorV2PromoteRule" } } }, "MonitorV2TransformSchedule": { "type": "object", "properties": { "freshnessGoal": { "$ref": "#/components/schemas/DurationNanoseconds" } } }, "MonitorV2CronSchedule": { "type": "object", "required": [ "timezone" ], "properties": { "cronConfig": { "type": "string", "description": "Crontab configuration for wall-clock scheduled evaluation." }, "timezone": { "type": "string", "description": "IANA timezone for interpreting cronConfig on the wall clock." }, "alarmMode": { "type": "string", "enum": [ "PerRun", "Ongoing" ], "description": "Controls how alarms are emitted across consecutive monitor evaluations. PerRun (the default when omitted) emits an independent zero-duration alarm per firing evaluation. Ongoing causes consecutive evaluations that re-assert the same (group, level) to extend a single ongoing alarm. Setting the value to Ongoing is gated by a customer feature flag.\n" } } }, "MonitorV2Scheduling": { "type": "object", "description": "Scheduling modes are mutually exclusive. Omit both transform and scheduled for service-chosen defaults. Set transform for continuous transform-driven evaluation, or scheduled for cron-based wall-clock evaluation.\n", "properties": { "transform": { "$ref": "#/components/schemas/MonitorV2TransformSchedule" }, "scheduled": { "$ref": "#/components/schemas/MonitorV2CronSchedule" } } }, "MonitorV2NoDataRule": { "type": "object", "properties": { "expiration": { "$ref": "#/components/schemas/DurationNanoseconds", "description": "How long the no-data alarm persists before auto-resolving. Omit for the backend default (~24 hours).\n" }, "threshold": { "$ref": "#/components/schemas/MonitorV2ThresholdRule", "description": "Threshold configuration. valueColumnName and aggregation must match the monitor's regular rules. compareValues must be empty.\n" } } }, "MonitorV2Definition": { "type": "object", "required": [ "inputQuery", "rules" ], "properties": { "inputQuery": { "$ref": "#/components/schemas/MultiStageQuery" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2Rule" } }, "lookbackTime": { "$ref": "#/components/schemas/DurationNanoseconds" }, "dataStabilizationDelay": { "$ref": "#/components/schemas/DurationNanoseconds" }, "maxAlertsPerHour": { "type": "integer" }, "groupings": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2Column" } }, "scheduling": { "description": "User-specified scheduling preference. When read back via GET, this reflects only what the user explicitly set, not the scheduling mode the backend is actually using. Null or omitted means the system chooses the best mode automatically. To see the resolved scheduling mode, use the top-level effectiveScheduling field instead.\n", "nullable": true, "$ref": "#/components/schemas/MonitorV2Scheduling" }, "noDataRules": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2NoDataRule" }, "description": "No-data rules that fire at NoData severity when no data arrives for the full lookback window. At most one entry for threshold monitors.\n" } } }, "MonitorV2BooleanOperator": { "type": "string", "enum": [ "And", "Or" ] }, "MonitorV2ComparisonExpression": { "type": "object", "properties": { "operator": { "$ref": "#/components/schemas/MonitorV2BooleanOperator" }, "subExpressions": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2ComparisonExpression" } }, "compareTerms": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2ComparisonTerm" } } } }, "MonitorV2ComparisonTerm": { "type": "object", "required": [ "comparison", "column" ], "properties": { "comparison": { "$ref": "#/components/schemas/MonitorV2Comparison" }, "column": { "$ref": "#/components/schemas/MonitorV2Column" } } }, "MonitorV2ActionType": { "type": "string", "enum": [ "Email", "PagerDuty", "Slack", "Webhook" ] }, "MonitorV2EmailAction": { "type": "object", "required": [ "subject" ], "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectId" } }, "addresses": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "body": { "type": "string" }, "fragments": { "type": "object" } } }, "MonitorV2HttpType": { "type": "string", "description": "The http type describes the method or verb to use in http webhooks.\nnote: As a convenience, the values POST and PUT will be accepted, but converted\nto the enumeration values Post and Put respectively.\n", "enum": [ "Post", "Put" ] }, "MonitorV2WebhookHeader": { "type": "object", "required": [ "header", "value" ], "properties": { "header": { "type": "string" }, "value": { "type": "string" } } }, "MonitorV2WebhookAction": { "type": "object", "required": [ "url", "method", "body" ], "properties": { "url": { "type": "string" }, "method": { "$ref": "#/components/schemas/MonitorV2HttpType" }, "headers": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2WebhookHeader" } }, "body": { "type": "string" }, "fragments": { "type": "object" } } }, "MonitorV2ActionDefinition": { "type": "object", "description": "The configuration of an action. `type` selects which payload applies:\n`Email` uses `email`, while `Webhook`, `Slack` and `PagerDuty` all use\n`webhook`. A PagerDuty action is a webhook posted to the PagerDuty\nEvents API, so its routing key is a field of the JSON template in\n`webhook.body` rather than a property of its own.\n", "required": [ "type" ], "properties": { "inline": { "type": "boolean", "description": "True when the action is private to its monitor, false when it is a\nshared action bound by `actionId`. Only an inline action's\ndefinition is written by a monitor create or update.\n" }, "name": { "type": "string", "description": "Names a shared action. An inline action is named internally: reads\ndo not return one and any value sent is replaced, so it may be\nomitted for inline actions.\n" }, "type": { "$ref": "#/components/schemas/MonitorV2ActionType" }, "email": { "$ref": "#/components/schemas/MonitorV2EmailAction" }, "webhook": { "$ref": "#/components/schemas/MonitorV2WebhookAction" } } }, "MonitorV2ActionRule": { "type": "object", "description": "Either the actionId or the definition must be present when setting.\nThe actionId references an existing shared action, while the\ndefinition would be used to configure an inline (private to a monitor)\naction. A read returns both: the actionId of the bound action and, for\nan inline action, the definition that can be edited and sent back.\n", "properties": { "actionId": { "$ref": "#/components/schemas/ObjectId" }, "levels": { "$ref": "#/components/schemas/MonitorV2AlarmLevel" }, "conditions": { "$ref": "#/components/schemas/MonitorV2ComparisonExpression" }, "sendEndNotifications": { "type": "boolean" }, "sendRemindersInterval": { "type": "boolean" }, "definition": { "$ref": "#/components/schemas/MonitorV2ActionDefinition" } } }, "MonitorV2PatchRequest": { "type": "object", "description": "Request body for `PATCH .../monitors/{id}`. Every property is optional. Only these\ntop-level keys participate in the update; see the operation description for merge vs\nwhole-value replacement rules.\n", "properties": { "name": { "type": "string" }, "disabled": { "type": "boolean" }, "description": { "type": "string" }, "ruleKind": { "$ref": "#/components/schemas/MonitorV2RuleKind" }, "definition": { "$ref": "#/components/schemas/MonitorV2Definition" }, "actionRules": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorV2ActionRule" } } } } } } } ````