Update a monitor user template to a new version

Note: This endpoint is in Preview. If you have any feedback, contact Datadog support.

PUT https://api.ap1.datadoghq.com/api/v2/monitor/template/{template_id}https://api.ap2.datadoghq.com/api/v2/monitor/template/{template_id}https://api.datadoghq.eu/api/v2/monitor/template/{template_id}https://api.ddog-gov.com/api/v2/monitor/template/{template_id}https://api.us2.ddog-gov.com/api/v2/monitor/template/{template_id}https://api.datadoghq.com/api/v2/monitor/template/{template_id}https://api.us3.datadoghq.com/api/v2/monitor/template/{template_id}https://api.us5.datadoghq.com/api/v2/monitor/template/{template_id}

Overview

Creates a new version of an existing monitor user template. This endpoint requires the monitor_config_policy_write permission.

Arguments

Path Parameters

Name

Type

Description

template_id [required]

string

ID of the monitor user template.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Monitor user template data.

attributes [required]

object

Attributes for a monitor user template.

description

string

A brief description of the monitor user template.

monitor_definition [required]

object

A valid monitor definition in the same format as the V1 Monitor API.

tags [required]

[string]

The definition of MonitorUserTemplateTags object.

template_variables

[object]

The definition of MonitorUserTemplateTemplateVariables object.

available_values

[string]

Available values for the variable.

defaults

[string]

Default values of the template variable.

name [required]

string

The name of the template variable.

tag_key

string

The tag key associated with the variable. This works the same as dashboard template variables.

title [required]

string

The title of the monitor user template.

id [required]

string

The unique identifier.

type [required]

enum

Monitor user template resource type. Allowed enum values: monitor-user-template

default: monitor-user-template

{
  "data": {
    "attributes": {
      "description": "A description.",
      "monitor_definition": {
        "message": "A msg.",
        "name": "A name example-monitor",
        "query": "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100",
        "type": "query alert"
      },
      "tags": [
        "integration:Azure"
      ],
      "template_variables": [
        {
          "available_values": [
            "value1",
            "value2"
          ],
          "defaults": [
            "defaultValue"
          ],
          "name": "regionName",
          "tag_key": "datacenter"
        }
      ],
      "title": "Postgres DB example-monitor"
    },
    "id": "00000000-0000-1234-0000-000000000000",
    "type": "monitor-user-template"
  }
}

Response

OK

Response for retrieving a monitor user template.

Expand All

Field

Type

Description

data

object

Monitor user template data.

attributes

object

A monitor user template object.

created

date-time

The created timestamp of the template.

description

string

A brief description of the monitor user template.

modified

date-time

The last modified timestamp. When the template version was created.

monitor_definition

object

A valid monitor definition in the same format as the V1 Monitor API.

tags

[string]

The definition of MonitorUserTemplateTags object.

template_variables

[object]

The definition of MonitorUserTemplateTemplateVariables object.

available_values

[string]

Available values for the variable.

defaults

[string]

Default values of the template variable.

name [required]

string

The name of the template variable.

tag_key

string

The tag key associated with the variable. This works the same as dashboard template variables.

title

string

The title of the monitor user template.

version

int64

The version of the monitor user template.

versions

[object]

All versions of the monitor user template.

created

date-time

The created timestamp of the template.

description

string

A brief description of the monitor user template.

id

string

The unique identifier. The initial version will match the template ID.

monitor_definition

object

A valid monitor definition in the same format as the V1 Monitor API.

tags

[string]

The definition of MonitorUserTemplateTags object.

template_variables

[object]

The definition of MonitorUserTemplateTemplateVariables object.

available_values

[string]

Available values for the variable.

defaults

[string]

Default values of the template variable.

name [required]

string

The name of the template variable.

tag_key

string

The tag key associated with the variable. This works the same as dashboard template variables.

title

string

The title of the monitor user template.

version

int64

The version of the monitor user template.

id

string

The unique identifier.

type

enum

Monitor user template resource type. Allowed enum values: monitor-user-template

default: monitor-user-template

{
  "data": {
    "attributes": {
      "created": "2024-01-02T03:04:23.274966+00:00",
      "description": "This is a template for monitoring user activity.",
      "modified": "2024-02-02T03:04:23.274966+00:00",
      "monitor_definition": {
        "message": "You may need to add web hosts if this is consistently high.",
        "name": "Bytes received on host0",
        "query": "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100",
        "type": "query alert"
      },
      "tags": [
        "product:Our Custom App",
        "integration:Azure"
      ],
      "template_variables": [
        {
          "available_values": [
            "value1",
            "value2"
          ],
          "defaults": [
            "defaultValue"
          ],
          "name": "regionName",
          "tag_key": "datacenter"
        }
      ],
      "title": "Postgres CPU Monitor",
      "version": 0,
      "versions": [
        {
          "created": "2024-01-02T03:04:23.274966+00:00",
          "description": "This is a template for monitoring user activity.",
          "id": "00000000-0000-1234-0000-000000000000",
          "monitor_definition": {
            "message": "You may need to add web hosts if this is consistently high.",
            "name": "Bytes received on host0",
            "query": "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100",
            "type": "query alert"
          },
          "tags": [
            "product:Our Custom App",
            "integration:Azure"
          ],
          "template_variables": [
            {
              "available_values": [
                "value1",
                "value2"
              ],
              "defaults": [
                "defaultValue"
              ],
              "name": "regionName",
              "tag_key": "datacenter"
            }
          ],
          "title": "Postgres CPU Monitor",
          "version": 0
        }
      ]
    },
    "id": "00000000-0000-1234-0000-000000000000",
    "type": "monitor-user-template"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          ## default
# 

# Path parameters
export template_id="CHANGE_ME"
# Curl command
curl -X PUT "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/monitor/template/${template_id}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "description": "This is a template for monitoring user activity.", "monitor_definition": { "message": "You may need to add web hosts if this is consistently high.", "name": "Bytes received on host0", "query": "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} \u003e 100", "type": "query alert" }, "tags": [ "product:Our Custom App", "integration:Azure" ], "template_variables": [ { "available_values": [ "value1", "value2" ], "defaults": [ "defaultValue" ], "name": "regionName", "tag_key": "datacenter" } ], "title": "Postgres CPU Monitor" }, "id": "00000000-0000-1234-0000-000000000000", "type": "monitor-user-template" } } EOF
// Update a monitor user template to a new version returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	// there is a valid "monitor_user_template" in the system
	MonitorUserTemplateDataID := os.Getenv("MONITOR_USER_TEMPLATE_DATA_ID")

	body := datadogV2.MonitorUserTemplateUpdateRequest{
		Data: datadogV2.MonitorUserTemplateUpdateData{
			Attributes: datadogV2.MonitorUserTemplateRequestAttributes{
				Description: *datadog.NewNullableString(datadog.PtrString("A description.")),
				MonitorDefinition: map[string]interface{}{
					"message": "A msg.",
					"name":    "A name example-monitor",
					"query":   "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100",
					"type":    "query alert",
				},
				Tags: []string{
					"integration:Azure",
				},
				TemplateVariables: []datadogV2.MonitorUserTemplateTemplateVariablesItems{
					{
						AvailableValues: []string{
							"value1",
							"value2",
						},
						Defaults: []string{
							"defaultValue",
						},
						Name:   "regionName",
						TagKey: datadog.PtrString("datacenter"),
					},
				},
				Title: "Postgres DB example-monitor",
			},
			Id:   MonitorUserTemplateDataID,
			Type: datadogV2.MONITORUSERTEMPLATERESOURCETYPE_MONITOR_USER_TEMPLATE,
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.UpdateMonitorUserTemplate", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewMonitorsApi(apiClient)
	resp, r, err := api.UpdateMonitorUserTemplate(ctx, MonitorUserTemplateDataID, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `MonitorsApi.UpdateMonitorUserTemplate`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `MonitorsApi.UpdateMonitorUserTemplate`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" go run "main.go"
// Update a monitor user template to a new version returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.MonitorsApi;
import com.datadog.api.client.v2.model.MonitorUserTemplateRequestAttributes;
import com.datadog.api.client.v2.model.MonitorUserTemplateResourceType;
import com.datadog.api.client.v2.model.MonitorUserTemplateResponse;
import com.datadog.api.client.v2.model.MonitorUserTemplateTemplateVariablesItems;
import com.datadog.api.client.v2.model.MonitorUserTemplateUpdateData;
import com.datadog.api.client.v2.model.MonitorUserTemplateUpdateRequest;
import java.util.Arrays;
import java.util.Collections;
import java.util.Map;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setUnstableOperationEnabled("v2.updateMonitorUserTemplate", true);
    MonitorsApi apiInstance = new MonitorsApi(defaultClient);

    // there is a valid "monitor_user_template" in the system
    String MONITOR_USER_TEMPLATE_DATA_ID = System.getenv("MONITOR_USER_TEMPLATE_DATA_ID");

    MonitorUserTemplateUpdateRequest body =
        new MonitorUserTemplateUpdateRequest()
            .data(
                new MonitorUserTemplateUpdateData()
                    .attributes(
                        new MonitorUserTemplateRequestAttributes()
                            .description("A description.")
                            .monitorDefinition(
                                Map.ofEntries(
                                    Map.entry("message", "A msg."),
                                    Map.entry("name", "A name example-monitor"),
                                    Map.entry(
                                        "query",
                                        "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100"),
                                    Map.entry("type", "query alert")))
                            .tags(Collections.singletonList("integration:Azure"))
                            .templateVariables(
                                Collections.singletonList(
                                    new MonitorUserTemplateTemplateVariablesItems()
                                        .availableValues(Arrays.asList("value1", "value2"))
                                        .defaults(Collections.singletonList("defaultValue"))
                                        .name("regionName")
                                        .tagKey("datacenter")))
                            .title("Postgres DB example-monitor"))
                    .id(MONITOR_USER_TEMPLATE_DATA_ID)
                    .type(MonitorUserTemplateResourceType.MONITOR_USER_TEMPLATE));

    try {
      MonitorUserTemplateResponse result =
          apiInstance.updateMonitorUserTemplate(MONITOR_USER_TEMPLATE_DATA_ID, body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling MonitorsApi#updateMonitorUserTemplate");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" java "Example.java"
"""
Update a monitor user template to a new version returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.monitors_api import MonitorsApi
from datadog_api_client.v2.model.monitor_user_template_request_attributes import MonitorUserTemplateRequestAttributes
from datadog_api_client.v2.model.monitor_user_template_resource_type import MonitorUserTemplateResourceType
from datadog_api_client.v2.model.monitor_user_template_template_variables_items import (
    MonitorUserTemplateTemplateVariablesItems,
)
from datadog_api_client.v2.model.monitor_user_template_update_data import MonitorUserTemplateUpdateData
from datadog_api_client.v2.model.monitor_user_template_update_request import MonitorUserTemplateUpdateRequest

# there is a valid "monitor_user_template" in the system
MONITOR_USER_TEMPLATE_DATA_ID = environ["MONITOR_USER_TEMPLATE_DATA_ID"]

body = MonitorUserTemplateUpdateRequest(
    data=MonitorUserTemplateUpdateData(
        attributes=MonitorUserTemplateRequestAttributes(
            description="A description.",
            monitor_definition=dict(
                [
                    ("message", "A msg."),
                    ("name", "A name example-monitor"),
                    ("query", "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100"),
                    ("type", "query alert"),
                ]
            ),
            tags=[
                "integration:Azure",
            ],
            template_variables=[
                MonitorUserTemplateTemplateVariablesItems(
                    available_values=[
                        "value1",
                        "value2",
                    ],
                    defaults=[
                        "defaultValue",
                    ],
                    name="regionName",
                    tag_key="datacenter",
                ),
            ],
            title="Postgres DB example-monitor",
        ),
        id=MONITOR_USER_TEMPLATE_DATA_ID,
        type=MonitorUserTemplateResourceType.MONITOR_USER_TEMPLATE,
    ),
)

configuration = Configuration()
configuration.unstable_operations["update_monitor_user_template"] = True
with ApiClient(configuration) as api_client:
    api_instance = MonitorsApi(api_client)
    response = api_instance.update_monitor_user_template(template_id=MONITOR_USER_TEMPLATE_DATA_ID, body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" python3 "example.py"
# Update a monitor user template to a new version returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.update_monitor_user_template".to_sym] = true
end
api_instance = DatadogAPIClient::V2::MonitorsAPI.new

# there is a valid "monitor_user_template" in the system
MONITOR_USER_TEMPLATE_DATA_ID = ENV["MONITOR_USER_TEMPLATE_DATA_ID"]

body = DatadogAPIClient::V2::MonitorUserTemplateUpdateRequest.new({
  data: DatadogAPIClient::V2::MonitorUserTemplateUpdateData.new({
    attributes: DatadogAPIClient::V2::MonitorUserTemplateRequestAttributes.new({
      description: "A description.",
      monitor_definition: {
        "message": "A msg.", "name": "A name example-monitor", "query": "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100", "type": "query alert",
      },
      tags: [
        "integration:Azure",
      ],
      template_variables: [
        DatadogAPIClient::V2::MonitorUserTemplateTemplateVariablesItems.new({
          available_values: [
            "value1",
            "value2",
          ],
          defaults: [
            "defaultValue",
          ],
          name: "regionName",
          tag_key: "datacenter",
        }),
      ],
      title: "Postgres DB example-monitor",
    }),
    id: MONITOR_USER_TEMPLATE_DATA_ID,
    type: DatadogAPIClient::V2::MonitorUserTemplateResourceType::MONITOR_USER_TEMPLATE,
  }),
})
p api_instance.update_monitor_user_template(MONITOR_USER_TEMPLATE_DATA_ID, body)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" rb "example.rb"
// Update a monitor user template to a new version returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_monitors::MonitorsAPI;
use datadog_api_client::datadogV2::model::MonitorUserTemplateRequestAttributes;
use datadog_api_client::datadogV2::model::MonitorUserTemplateResourceType;
use datadog_api_client::datadogV2::model::MonitorUserTemplateTemplateVariablesItems;
use datadog_api_client::datadogV2::model::MonitorUserTemplateUpdateData;
use datadog_api_client::datadogV2::model::MonitorUserTemplateUpdateRequest;
use serde_json::Value;
use std::collections::BTreeMap;

#[tokio::main]
async fn main() {
    // there is a valid "monitor_user_template" in the system
    let monitor_user_template_data_id = std::env::var("MONITOR_USER_TEMPLATE_DATA_ID").unwrap();
    let body = MonitorUserTemplateUpdateRequest::new(MonitorUserTemplateUpdateData::new(
        MonitorUserTemplateRequestAttributes::new(
            BTreeMap::from([
                ("message".to_string(), Value::from("A msg.")),
                ("name".to_string(), Value::from("A name example-monitor")),
                (
                    "query".to_string(),
                    Value::from("avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100"),
                ),
                ("type".to_string(), Value::from("query alert")),
            ]),
            vec!["integration:Azure".to_string()],
            "Postgres DB example-monitor".to_string(),
        )
        .description(Some("A description.".to_string()))
        .template_variables(vec![MonitorUserTemplateTemplateVariablesItems::new(
            "regionName".to_string(),
        )
        .available_values(vec!["value1".to_string(), "value2".to_string()])
        .defaults(vec!["defaultValue".to_string()])
        .tag_key("datacenter".to_string())]),
        monitor_user_template_data_id.clone(),
        MonitorUserTemplateResourceType::MONITOR_USER_TEMPLATE,
    ));
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.UpdateMonitorUserTemplate", true);
    let api = MonitorsAPI::with_config(configuration);
    let resp = api
        .update_monitor_user_template(monitor_user_template_data_id.clone(), body)
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * Update a monitor user template to a new version returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
configuration.unstableOperations["v2.updateMonitorUserTemplate"] = true;
const apiInstance = new v2.MonitorsApi(configuration);

// there is a valid "monitor_user_template" in the system
const MONITOR_USER_TEMPLATE_DATA_ID = process.env
  .MONITOR_USER_TEMPLATE_DATA_ID as string;

const params: v2.MonitorsApiUpdateMonitorUserTemplateRequest = {
  body: {
    data: {
      attributes: {
        description: "A description.",
        monitorDefinition: {
          message: "A msg.",
          name: "A name example-monitor",
          query: "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} > 100",
          type: "query alert",
        },
        tags: ["integration:Azure"],
        templateVariables: [
          {
            availableValues: ["value1", "value2"],
            defaults: ["defaultValue"],
            name: "regionName",
            tagKey: "datacenter",
          },
        ],
        title: "Postgres DB example-monitor",
      },
      id: MONITOR_USER_TEMPLATE_DATA_ID,
      type: "monitor-user-template",
    },
  },
  templateId: MONITOR_USER_TEMPLATE_DATA_ID,
};

apiInstance
  .updateMonitorUserTemplate(params)
  .then((data: v2.MonitorUserTemplateResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" tsc "example.ts"