Deletes a channel -- but only once nothing still uses it. If alert rules still point at it, check what's using it and either reassign those rules to a different channel or remove them yourself first.

Having trouble reaching the API, or logging in from another machine? See Network Access & Authentication Security -- by default the Api only answers localhost, and PowerShell needs an extra flag once it does answer elsewhere.

Order of Operations

  1. Authenticate to the API.
  2. Get the channel's id (from List Alert Channels).
  3. Check what still uses it.
  4. Reassign those rules (or remove them), then delete.

The calls

GET    /api/alert-channels/{alertChannelId}/usage
POST   /api/alert-channels/{alertChannelId}/reassign
DELETE /api/alert-channels/{alertChannelId}

Permission needed: Credential.View to check usage, Credential.Manage to reassign or delete.

C# example

var jsonOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web);

// Step 1: Authenticate to the API.
using var handler = new HttpClientHandler { UseDefaultCredentials = true };
using var client = new HttpClient(handler) { BaseAddress = new Uri("http://your-minion-agent-server:5443") };
client.DefaultRequestHeaders.Add("X-App-Name", "MyIntegration");

// Step 2: You already have the channel's id.
var alertChannelId = 5;

// Step 3: Check what still uses it.
var usage = await client.GetFromJsonAsync<AlertChannelUsageInfo[]>($"/api/alert-channels/{alertChannelId}/usage", jsonOptions);
foreach (var u in usage!)
    Console.WriteLine($"rule {u.JobAlertRuleId}: {u.Label} on {u.RunStatusName}");

// Step 4: Reassign every rule on it to a replacement channel, then delete.
if (usage.Length > 0)
{
    var reassign = new ReassignAlertChannelRequest(ToAlertChannelId: 2);
    var reassignResponse = await client.PostAsJsonAsync($"/api/alert-channels/{alertChannelId}/reassign", reassign, jsonOptions);
    reassignResponse.EnsureSuccessStatusCode();
}
var deleteResponse = await client.DeleteAsync($"/api/alert-channels/{alertChannelId}");
deleteResponse.EnsureSuccessStatusCode();
Console.WriteLine("Deleted.");

record AlertChannelUsageInfo(int JobAlertRuleId, int? JobId, int? JobStepId, string Label, byte TriggerOnRunStatusCode, string RunStatusName);
record ReassignAlertChannelRequest(int ToAlertChannelId, int[]? JobAlertRuleIds = null);

Not on a domain machine? Swap in the app-account login from Calling the API From Your Own Code.

PowerShell example

# Step 1: Authenticate to the API.
$headers = @{ "X-App-Name" = "MyIntegration" }

# Step 2: You already have the channel's id.
$alertChannelId = 5

# Step 3: Check what still uses it. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$usage = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/alert-channels/$alertChannelId/usage" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$usage | ForEach-Object { "rule $($_.jobAlertRuleId): $($_.label) on $($_.runStatusName)" }

# Step 4: Reassign every rule on it to a replacement channel, then delete.
if ($usage.Count -gt 0) {
    $reassign = @{ ToAlertChannelId = 2 } | ConvertTo-Json
    Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/alert-channels/$alertChannelId/reassign" `
        -Method Post -Body $reassign -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
}
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/alert-channels/$alertChannelId" -Method Delete -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Deleted."

ToAlertChannelId in the reassign body is required; JobAlertRuleIds is optional -- omit it to reassign every rule on the channel, or pass specific rule ids to move only some of them (any rule that would collide with one the target channel already has for the same job/step + status is silently dropped rather than duplicated).

What you get back

GET .../usage -- 200 OK, an array (empty if nothing uses it):

[ { "jobAlertRuleId": 14, "jobId": 214, "jobStepId": null, "label": "Nightly ETL", "triggerOnRunStatusCode": 8, "runStatusName": "Failed" } ]

POST .../reassign -- 204 No Content, DELETE -- 204 No Content -- no body for either.

Codes this call can return

See API Response Codes for what each one means in general. For these calls:

  • 200 -- the usage list.
  • 204 -- reassigned or deleted.
  • 400 -- (reassign) ToAlertChannelId is the same channel you're reassigning from.
  • 403 -- you don't have the required permission.
  • 409 -- (delete) the channel is still used by one or more alert rules -- reassign or remove them first.

What gets audited

Reassign is recorded as AlertChannel / Reassign Alert Rules; delete as AlertChannel / Delete Alert Channel. The usage check isn't audited (it's a read).

See also: List Alert Channels, Create an Alert Channel, Manage Alert Rules.