Update an alert
curl --request PATCH \
--url https://api.coval.dev/v1/alerts/{alert_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"enabled": true,
"name": "<string>",
"description": "<string>",
"evaluation_type": "ON_RUN_COMPLETE",
"cooldown_seconds": 43200,
"custom_message_template": "<string>",
"agent_ids": [
"<string>"
],
"required_tags": [
"<string>"
],
"scheduled_run_ids": [
"<string>"
],
"customer_metadata": {},
"conditions": [
{
"metric_id": "<string>",
"threshold_float": 123,
"threshold_string": "<string>",
"window_size_days": 183,
"window_size_runs": 5000,
"match_value": "<string>",
"baseline_id": "<string>",
"sigma_threshold": 1,
"warm_up_count": 1
}
],
"channels": [
{
"config": {}
}
]
}
'import requests
url = "https://api.coval.dev/v1/alerts/{alert_id}"
payload = {
"enabled": True,
"name": "<string>",
"description": "<string>",
"evaluation_type": "ON_RUN_COMPLETE",
"cooldown_seconds": 43200,
"custom_message_template": "<string>",
"agent_ids": ["<string>"],
"required_tags": ["<string>"],
"scheduled_run_ids": ["<string>"],
"customer_metadata": {},
"conditions": [
{
"metric_id": "<string>",
"threshold_float": 123,
"threshold_string": "<string>",
"window_size_days": 183,
"window_size_runs": 5000,
"match_value": "<string>",
"baseline_id": "<string>",
"sigma_threshold": 1,
"warm_up_count": 1
}
],
"channels": [{ "config": {} }]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
enabled: true,
name: '<string>',
description: '<string>',
evaluation_type: 'ON_RUN_COMPLETE',
cooldown_seconds: 43200,
custom_message_template: '<string>',
agent_ids: ['<string>'],
required_tags: ['<string>'],
scheduled_run_ids: ['<string>'],
customer_metadata: {},
conditions: [
{
metric_id: '<string>',
threshold_float: 123,
threshold_string: '<string>',
window_size_days: 183,
window_size_runs: 5000,
match_value: '<string>',
baseline_id: '<string>',
sigma_threshold: 1,
warm_up_count: 1
}
],
channels: [{config: {}}]
})
};
fetch('https://api.coval.dev/v1/alerts/{alert_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coval.dev/v1/alerts/{alert_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'enabled' => true,
'name' => '<string>',
'description' => '<string>',
'evaluation_type' => 'ON_RUN_COMPLETE',
'cooldown_seconds' => 43200,
'custom_message_template' => '<string>',
'agent_ids' => [
'<string>'
],
'required_tags' => [
'<string>'
],
'scheduled_run_ids' => [
'<string>'
],
'customer_metadata' => [
],
'conditions' => [
[
'metric_id' => '<string>',
'threshold_float' => 123,
'threshold_string' => '<string>',
'window_size_days' => 183,
'window_size_runs' => 5000,
'match_value' => '<string>',
'baseline_id' => '<string>',
'sigma_threshold' => 1,
'warm_up_count' => 1
]
],
'channels' => [
[
'config' => [
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coval.dev/v1/alerts/{alert_id}"
payload := strings.NewReader("{\n \"enabled\": true,\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"evaluation_type\": \"ON_RUN_COMPLETE\",\n \"cooldown_seconds\": 43200,\n \"custom_message_template\": \"<string>\",\n \"agent_ids\": [\n \"<string>\"\n ],\n \"required_tags\": [\n \"<string>\"\n ],\n \"scheduled_run_ids\": [\n \"<string>\"\n ],\n \"customer_metadata\": {},\n \"conditions\": [\n {\n \"metric_id\": \"<string>\",\n \"threshold_float\": 123,\n \"threshold_string\": \"<string>\",\n \"window_size_days\": 183,\n \"window_size_runs\": 5000,\n \"match_value\": \"<string>\",\n \"baseline_id\": \"<string>\",\n \"sigma_threshold\": 1,\n \"warm_up_count\": 1\n }\n ],\n \"channels\": [\n {\n \"config\": {}\n }\n ]\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.coval.dev/v1/alerts/{alert_id}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"enabled\": true,\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"evaluation_type\": \"ON_RUN_COMPLETE\",\n \"cooldown_seconds\": 43200,\n \"custom_message_template\": \"<string>\",\n \"agent_ids\": [\n \"<string>\"\n ],\n \"required_tags\": [\n \"<string>\"\n ],\n \"scheduled_run_ids\": [\n \"<string>\"\n ],\n \"customer_metadata\": {},\n \"conditions\": [\n {\n \"metric_id\": \"<string>\",\n \"threshold_float\": 123,\n \"threshold_string\": \"<string>\",\n \"window_size_days\": 183,\n \"window_size_runs\": 5000,\n \"match_value\": \"<string>\",\n \"baseline_id\": \"<string>\",\n \"sigma_threshold\": 1,\n \"warm_up_count\": 1\n }\n ],\n \"channels\": [\n {\n \"config\": {}\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/alerts/{alert_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"enabled\": true,\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"evaluation_type\": \"ON_RUN_COMPLETE\",\n \"cooldown_seconds\": 43200,\n \"custom_message_template\": \"<string>\",\n \"agent_ids\": [\n \"<string>\"\n ],\n \"required_tags\": [\n \"<string>\"\n ],\n \"scheduled_run_ids\": [\n \"<string>\"\n ],\n \"customer_metadata\": {},\n \"conditions\": [\n {\n \"metric_id\": \"<string>\",\n \"threshold_float\": 123,\n \"threshold_string\": \"<string>\",\n \"window_size_days\": 183,\n \"window_size_runs\": 5000,\n \"match_value\": \"<string>\",\n \"baseline_id\": \"<string>\",\n \"sigma_threshold\": 1,\n \"warm_up_count\": 1\n }\n ],\n \"channels\": [\n {\n \"config\": {}\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"ulid": "01HZ0EXAMPLE00000000000000",
"name": "Latency SLA Alert",
"status": "ACTIVE",
"enabled": true,
"evaluation_type": "ON_RUN_COMPLETE",
"conversation_source": "ALL",
"match_mode": "ALL",
"cooldown_seconds": 43200,
"create_time": "2023-11-07T05:31:56Z",
"update_time": "2023-11-07T05:31:56Z",
"description": "",
"custom_message_template": "<string>",
"agent_ids": [
"<string>"
],
"required_tags": [
"<string>"
],
"scheduled_run_ids": [
"<string>"
],
"customer_metadata": {},
"trigger_count": 123,
"last_triggered_at": "2023-11-07T05:31:56Z",
"conditions": [
{
"ulid": "<string>",
"aggregation": "SINGLE",
"operator": "GT",
"metric_id": "<string>",
"threshold_float": 123,
"threshold_string": "<string>",
"window_size_days": 183,
"window_size_runs": 5000,
"match_value": "<string>",
"match_mode": "exact",
"baseline_id": "<string>",
"sigma_threshold": 1,
"direction": "above",
"warm_up_count": 1
}
],
"channels": [
{
"ulid": "<string>",
"channel_type": "SLACK",
"config": {}
}
]
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Invalid request body",
"details": [
{
"field": "conditions",
"description": "Value error, List should have at least 1 item after validation"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "X-API-Key",
"description": "Invalid or missing API key"
}
]
}
}{
"error": {
"code": "PERMISSION_DENIED",
"message": "Insufficient permissions",
"details": [
{
"field": "permissions",
"description": "Required scope: alerts:read"
}
]
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Alert not found",
"details": [
{
"field": "alert_id",
"description": "Alert '01HZ0EXAMPLE00000000000000' not found"
}
]
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "<string>",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Alerts
Update an alert
Partially updates an alert. All fields are optional; omitted fields retain their current values (PATCH semantics).
When conditions or channels are provided, they replace the
existing set atomically (delete old, create new).
PATCH
/
alerts
/
{alert_id}
Update an alert
curl --request PATCH \
--url https://api.coval.dev/v1/alerts/{alert_id} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"enabled": true,
"name": "<string>",
"description": "<string>",
"evaluation_type": "ON_RUN_COMPLETE",
"cooldown_seconds": 43200,
"custom_message_template": "<string>",
"agent_ids": [
"<string>"
],
"required_tags": [
"<string>"
],
"scheduled_run_ids": [
"<string>"
],
"customer_metadata": {},
"conditions": [
{
"metric_id": "<string>",
"threshold_float": 123,
"threshold_string": "<string>",
"window_size_days": 183,
"window_size_runs": 5000,
"match_value": "<string>",
"baseline_id": "<string>",
"sigma_threshold": 1,
"warm_up_count": 1
}
],
"channels": [
{
"config": {}
}
]
}
'import requests
url = "https://api.coval.dev/v1/alerts/{alert_id}"
payload = {
"enabled": True,
"name": "<string>",
"description": "<string>",
"evaluation_type": "ON_RUN_COMPLETE",
"cooldown_seconds": 43200,
"custom_message_template": "<string>",
"agent_ids": ["<string>"],
"required_tags": ["<string>"],
"scheduled_run_ids": ["<string>"],
"customer_metadata": {},
"conditions": [
{
"metric_id": "<string>",
"threshold_float": 123,
"threshold_string": "<string>",
"window_size_days": 183,
"window_size_runs": 5000,
"match_value": "<string>",
"baseline_id": "<string>",
"sigma_threshold": 1,
"warm_up_count": 1
}
],
"channels": [{ "config": {} }]
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
enabled: true,
name: '<string>',
description: '<string>',
evaluation_type: 'ON_RUN_COMPLETE',
cooldown_seconds: 43200,
custom_message_template: '<string>',
agent_ids: ['<string>'],
required_tags: ['<string>'],
scheduled_run_ids: ['<string>'],
customer_metadata: {},
conditions: [
{
metric_id: '<string>',
threshold_float: 123,
threshold_string: '<string>',
window_size_days: 183,
window_size_runs: 5000,
match_value: '<string>',
baseline_id: '<string>',
sigma_threshold: 1,
warm_up_count: 1
}
],
channels: [{config: {}}]
})
};
fetch('https://api.coval.dev/v1/alerts/{alert_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coval.dev/v1/alerts/{alert_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'enabled' => true,
'name' => '<string>',
'description' => '<string>',
'evaluation_type' => 'ON_RUN_COMPLETE',
'cooldown_seconds' => 43200,
'custom_message_template' => '<string>',
'agent_ids' => [
'<string>'
],
'required_tags' => [
'<string>'
],
'scheduled_run_ids' => [
'<string>'
],
'customer_metadata' => [
],
'conditions' => [
[
'metric_id' => '<string>',
'threshold_float' => 123,
'threshold_string' => '<string>',
'window_size_days' => 183,
'window_size_runs' => 5000,
'match_value' => '<string>',
'baseline_id' => '<string>',
'sigma_threshold' => 1,
'warm_up_count' => 1
]
],
'channels' => [
[
'config' => [
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coval.dev/v1/alerts/{alert_id}"
payload := strings.NewReader("{\n \"enabled\": true,\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"evaluation_type\": \"ON_RUN_COMPLETE\",\n \"cooldown_seconds\": 43200,\n \"custom_message_template\": \"<string>\",\n \"agent_ids\": [\n \"<string>\"\n ],\n \"required_tags\": [\n \"<string>\"\n ],\n \"scheduled_run_ids\": [\n \"<string>\"\n ],\n \"customer_metadata\": {},\n \"conditions\": [\n {\n \"metric_id\": \"<string>\",\n \"threshold_float\": 123,\n \"threshold_string\": \"<string>\",\n \"window_size_days\": 183,\n \"window_size_runs\": 5000,\n \"match_value\": \"<string>\",\n \"baseline_id\": \"<string>\",\n \"sigma_threshold\": 1,\n \"warm_up_count\": 1\n }\n ],\n \"channels\": [\n {\n \"config\": {}\n }\n ]\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.coval.dev/v1/alerts/{alert_id}")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"enabled\": true,\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"evaluation_type\": \"ON_RUN_COMPLETE\",\n \"cooldown_seconds\": 43200,\n \"custom_message_template\": \"<string>\",\n \"agent_ids\": [\n \"<string>\"\n ],\n \"required_tags\": [\n \"<string>\"\n ],\n \"scheduled_run_ids\": [\n \"<string>\"\n ],\n \"customer_metadata\": {},\n \"conditions\": [\n {\n \"metric_id\": \"<string>\",\n \"threshold_float\": 123,\n \"threshold_string\": \"<string>\",\n \"window_size_days\": 183,\n \"window_size_runs\": 5000,\n \"match_value\": \"<string>\",\n \"baseline_id\": \"<string>\",\n \"sigma_threshold\": 1,\n \"warm_up_count\": 1\n }\n ],\n \"channels\": [\n {\n \"config\": {}\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coval.dev/v1/alerts/{alert_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"enabled\": true,\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"evaluation_type\": \"ON_RUN_COMPLETE\",\n \"cooldown_seconds\": 43200,\n \"custom_message_template\": \"<string>\",\n \"agent_ids\": [\n \"<string>\"\n ],\n \"required_tags\": [\n \"<string>\"\n ],\n \"scheduled_run_ids\": [\n \"<string>\"\n ],\n \"customer_metadata\": {},\n \"conditions\": [\n {\n \"metric_id\": \"<string>\",\n \"threshold_float\": 123,\n \"threshold_string\": \"<string>\",\n \"window_size_days\": 183,\n \"window_size_runs\": 5000,\n \"match_value\": \"<string>\",\n \"baseline_id\": \"<string>\",\n \"sigma_threshold\": 1,\n \"warm_up_count\": 1\n }\n ],\n \"channels\": [\n {\n \"config\": {}\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"ulid": "01HZ0EXAMPLE00000000000000",
"name": "Latency SLA Alert",
"status": "ACTIVE",
"enabled": true,
"evaluation_type": "ON_RUN_COMPLETE",
"conversation_source": "ALL",
"match_mode": "ALL",
"cooldown_seconds": 43200,
"create_time": "2023-11-07T05:31:56Z",
"update_time": "2023-11-07T05:31:56Z",
"description": "",
"custom_message_template": "<string>",
"agent_ids": [
"<string>"
],
"required_tags": [
"<string>"
],
"scheduled_run_ids": [
"<string>"
],
"customer_metadata": {},
"trigger_count": 123,
"last_triggered_at": "2023-11-07T05:31:56Z",
"conditions": [
{
"ulid": "<string>",
"aggregation": "SINGLE",
"operator": "GT",
"metric_id": "<string>",
"threshold_float": 123,
"threshold_string": "<string>",
"window_size_days": 183,
"window_size_runs": 5000,
"match_value": "<string>",
"match_mode": "exact",
"baseline_id": "<string>",
"sigma_threshold": 1,
"direction": "above",
"warm_up_count": 1
}
],
"channels": [
{
"ulid": "<string>",
"channel_type": "SLACK",
"config": {}
}
]
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Invalid request body",
"details": [
{
"field": "conditions",
"description": "Value error, List should have at least 1 item after validation"
}
]
}
}{
"error": {
"code": "UNAUTHENTICATED",
"message": "Authentication failed",
"details": [
{
"field": "X-API-Key",
"description": "Invalid or missing API key"
}
]
}
}{
"error": {
"code": "PERMISSION_DENIED",
"message": "Insufficient permissions",
"details": [
{
"field": "permissions",
"description": "Required scope: alerts:read"
}
]
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Alert not found",
"details": [
{
"field": "alert_id",
"description": "Alert '01HZ0EXAMPLE00000000000000' not found"
}
]
}
}{
"error": {
"code": "INVALID_ARGUMENT",
"message": "<string>",
"details": [
{
"field": "<string>",
"description": "<string>"
}
]
}
}{
"error": {
"code": "INTERNAL",
"message": "Internal server error",
"details": [
{
"description": "An unexpected error occurred"
}
]
}
}Authorizations
API key for authentication
Headers
Workspace that scopes this operation. When omitted, the organization's active default workspace is used when one can be resolved.
Required string length:
1 - 26Path Parameters
Alert ULID
Pattern:
^[0-9A-Z]{26}$Body
application/json
Pause or resume the whole alert rule. Set false to pause, true to resume; omission or null leaves the current value unchanged.
Maximum string length:
200Maximum string length:
2000When the alert evaluates
Available options:
ON_RUN_COMPLETE Which conversations the alert applies to
Available options:
ALL, UPLOADED, SIMULATED How multiple conditions are combined (AND vs OR)
Available options:
ALL, ANY Required range:
0 <= x <= 86400Exact scalar Run customer metadata filters, joined by AND. Literal keys are 1–256 characters; values are case-sensitive text. A list of values matches when the metadata equals any one of them. Numbers and booleans use JSON text; missing, null, array, and object values do not match. Omission or null leaves filters unchanged. An empty object clears filters only if at least one metric condition remains.
Show child attributes
Show child attributes
Replaces all existing conditions. With ALL match mode, an empty list matches every conversation passing the remaining filters. ANY requires a metric condition or customer_metadata filter. Null or omission preserves conditions.
Show child attributes
Show child attributes
Replaces all channels; at most one HUMAN_REVIEW channel is allowed. Null or omission preserves channels.
Show child attributes
Show child attributes
Response
Alert updated
Authoring timestamp; null when unknown.
Canonical author user ID; null when unknown.
Authoring timestamp; null when unknown.
Canonical author user ID; null when unknown.
Alert ULID
Pattern:
^[0-9A-Z]{26}$Example:
"01HZ0EXAMPLE00000000000000"
Human-readable alert name
Maximum string length:
200Example:
"Latency SLA Alert"
Alert status
Available options:
ACTIVE, DELETED Whether the alert evaluates and dispatches. Legacy alerts without this value are treated as enabled.
When the alert evaluates
Available options:
ON_RUN_COMPLETE Which conversations the alert applies to
Available options:
ALL, UPLOADED, SIMULATED How multiple conditions are combined (AND vs OR)
Available options:
ALL, ANY Minimum seconds between triggers
Required range:
0 <= x <= 86400Creation timestamp
Last update timestamp
Optional description
Custom notification message template
Maximum string length:
5000Restrict to specific agent IDs
Restrict to runs with these tags
Restrict to runs originating from these scheduled runs
Exact scalar Run customer metadata filters, joined by AND. Literal keys are 1–256 characters; values are case-sensitive text. A list of values matches when the metadata equals any one of them. Numbers and booleans use JSON text; missing, null, array, and object values do not match. An empty object applies no metadata filter.
Show child attributes
Show child attributes
Number of times this alert has triggered
Last trigger timestamp
Evaluation conditions
Show child attributes
Show child attributes
Notification channels
Show child attributes
Show child attributes
Was this page helpful?