addBotRecipe

A Graze API POST request that creates a new Cookbook Bot Recipe. To create Recipes using the Value Recipe and Value Recipe v2 recipe types, use addValueRecipe. See Recipe Types for more information.Recipe Types

Back to Graze API EndPoint Reference.

Request arguments

Endpoint addBotRecipe takes the following request arguments:

Name	Type	Required	Description
`auth_token`	String	Yes	A valid `auth_token` returned from the `authenticate` request. Alternatively, basic authenticate headers can be used in place of this parameter. See the authenticate endpoint for more information and usage examples.
`cookbooks`	Array of Strings	No	A list of the Cookbooks that this Recipe belongs to. You can add Cookbooks here or, when you create a Cookbook, you can assign the Recipes to it.
`name`	String	Yes	Name of the Recipe. Use a unique and descriptive name.
`description`	String	No	Description of the Recipe. Default is the Recipe `name`.
`alert_threshold`	Positive Integer	No	Minimum number of alerts required before Cookbook creates a Situation.
`trigger`	String	No	A filter that determines the alerts that Cookbook considers for Situation creation. Cookbook includes alerts that match the trigger filter. By default Cookbook only includes alerts with a severity of 'Critical'. For details on creating a filter, see Filter Search Data. To set a vertex entropy trigger filter, see Configure Topology-based Clustering with Vertex Entropy for more information. Default is an empty string.
`exclusion`	String	No	A filter that determines the alerts to exclude from Situation creation. Cookbook ignores alerts that match the exclusion filter. For details on creating a filter, see Filter Search Data. To set a vertex entropy exclusion filter, see Configure Topology-based Clustering with Vertex Entropy for more information. Default is an empty string.
`seed_alert`	String	No	A filter that determines whether to create a Situation from a seed alert. The seed alert must meet both the `trigger`, `exclusion` and `seed_alert` criteria to create a Situation. Cookbook considers subsequent alerts for clustering if they meet the trigger and exclusion filter criteria. Alerts that arrive prior to the seed alert that met the trigger and exclusion filter criteria do not form Situations. For details on creating a filter, see Filter Search Data. To set a vertex entropy seed alert filter, see Configure Topology-based Clustering with Vertex Entropy for more information. Default is an empty string.
`rate`	Double	No	Rate, in number of alerts per second. Cookbook clusters alerts if they arrive at a higher rate than is specified here. Cookbook uses `rate` together with `min_sample_size` and `max_sample_size` to determines whether to cluster alerts into Situations. See Cookbook and Recipe Examples for more information. Default is 0 which means that Cookbook does not use the rate to cluster alerts.
`min_sample_size`	Positive Integer	No	Number of alerts that must arrive before the Cookbook starts to calculate the alert rate. See Cookbook and Recipe Examples for more information. Default is 5. Valid only if `rate` is non-zero.
`max_sample_size`	Positive Integer	No	Maximum number of alerts that are considered in the alert rate calculation. When more than this number of alerts have arrived, Cookbook discards the oldest alerts and calculates the alert rate based on the number of alerts in the `max_sample_size`. See Cookbook and Recipe Examples for more information. Default is 10. Valid only if `rate` is non-zero.
`cook_for`	Positive Integer	No	Minimum time period, in seconds, that the Cookbook Recipe clusters alerts for before it resets and starts a new cluster. See Cookbook and Recipe Examples for more information. If you set a different `cook_for` time for a Recipe, it overrides the Cookbook value. Recipes without a `cook_for` time inherit the value from the Cookbook.
`cook_for_extension`	Positive Integer	No	Time period that the Cookbook Recipe can extend clustering alerts for before it resets and starts a new cluster. Setting this value enables the cook for auto-extension feature for this Cookbook. As Cookbook receives related alerts, it continues to extend the total clustering time until the `max_cook_for` period is reached. Used in conjunction with the `max_cook_for` value, the `cook_for_extension` period helps to ensure that Cookbook continues to cluster alerts together that are related to the same failure. The `cook_for_extension` period only applies to new related alerts; it does not apply to existing alerts that are updated with new events. See Cookbook and Recipe Examples for more information. If you set a different `cook_for_extension` time for a Recipe, it overrides the Cookbook value. Recipes without a `cook_for_extension` time inherit the value from the Cookbook.
`max_cook_for`	Positive Integer	No	Maximum time period that the Cookbook Recipe clusters alerts for before it resets and starts a new cluster. It works in conjunction with the `cook_for_extension` time to help ensure that Cookbook continues to cluster alerts together that are related to the same failure. This value is ignored unless the `cook_for_extension` time is specified. See Cookbook and Recipe Examples for more information. If you set a different `max_cook_for` time for a Recipe, it overrides the Cookbook value. Recipes without a `max_cook_for` value inherit the value from the Cookbook.
`cluster_by`	String	No	Determines Cookbook's clustering behavior. Set to an empty string to use the Cookbook `cluster_by` setting. Set to `first_match` so that Cookbook adds alerts to the first cluster over the similarity threshold value. Set to `closest_match` to add alerts to the cluster with the highest similarity greater than the similarity threshold value. This option may be less efficient because Cookbook needs to compare alerts against each cluster in a Recipe. Default is an empty string which means the Recipe uses the Cookbook setting. If you set a different `cluster_by` value for a Recipe, it overrides the Cookbook value. Recipes without a `cluster_by` value inherit the value from the Cookbook.
`initialize_function`	JSON Function Name	No	Default is `initBuckets`.
`member_function`	JSON Function Name	No	Default is `checkBucket`.
`can_start_cluster`	JSON Function Name	No	Default is null.
`use_in_recipe`	JSON Function Name	No	Name of the function that will determine whether to consider an event for clustering (similar to a trigger filter). Default is null.
`similarity`	Double	No	Value between 0 and 1. Default is 0.8.

Response

Endpoint addBotRecipe returns the following response:

Type	Description
HTTP Code	HTTP status or error code indicating request success or failure. See HTTP status code definitions for more information.

Successful requests return a JSON object containing the following:

Name	Type	Description
`id`	Integer	ID of the new Bot Recipe.

Examples

The following examples demonstrate typical use of endpoint addBotRecipe:

Request example

Example cURL request to create a new Bot Recipe "BotRecipe2":

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addBotRecipe" -H "Content-Type: application/json; charset=UTF-8" -d '{"cookbooks" : ["GrazeCookbook1"],"name":"BotRecipe2","alert_threshold":1}'

Response example

Successful response providing the ID of the new Bot Recipe that has been created:

{
    "id": 4
}

In this section: