An alert rule ties one job or one step (never both -- there are separate endpoints for each) to a run status (like Failed or Succeeded), a channel to notify, a message style for the content, and optionally an alert schedule that restricts it to a time window. There's no update endpoint -- to change a rule, delete and recreate it.

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 job's or step's id, the channel's id, and the message style's id.
  3. Create the rule.

The calls

GET    /api/jobs/{jobId}/alert-rules
POST   /api/jobs/{jobId}/alert-rules
GET    /api/job-steps/{jobStepId}/alert-rules
POST   /api/job-steps/{jobStepId}/alert-rules
DELETE /api/alert-rules/{jobAlertRuleId}

Permission needed: Job.View to list, Job.Edit to create or delete, on whichever job/step the rule belongs to (resolved automatically for the delete call from the rule itself).

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 job's id, the channel's id, and the message style's id.
var jobId = 214;
var alertChannelId = 5;
var messageStyleId = 3;

// Step 3: Create the rule -- notify on Failed (run status code 8).
var newRule = new CreateAlertRuleRequest(AlertChannelId: alertChannelId, TriggerOnRunStatusCode: 8, MessageStyleId: messageStyleId, AlertScheduleId: null);
var response = await client.PostAsJsonAsync($"/api/jobs/{jobId}/alert-rules", newRule, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedIdResponse>(jsonOptions);
Console.WriteLine($"Created rule id: {created!.Id}");

// List every rule on the job.
var rules = await client.GetFromJsonAsync<AlertRuleInfo[]>($"/api/jobs/{jobId}/alert-rules", jsonOptions);
foreach (var rule in rules!)
    Console.WriteLine($"{rule.JobAlertRuleId}: on {rule.RunStatusName} -> {rule.ChannelName} using '{rule.StyleName}'");

// Delete it later.
var deleteResponse = await client.DeleteAsync($"/api/alert-rules/{created.Id}");
deleteResponse.EnsureSuccessStatusCode();

record CreateAlertRuleRequest(int AlertChannelId, byte TriggerOnRunStatusCode, int MessageStyleId, int? AlertScheduleId = null);
record CreatedIdResponse(int Id);
record AlertRuleInfo(int JobAlertRuleId, byte TriggerOnRunStatusCode, string RunStatusName, int AlertChannelId, string ChannelName,
    int MessageStyleId, string StyleName, int? AlertScheduleId, string? ScheduleName, bool IsActive);

For a step instead of a job, use /api/job-steps/{jobStepId}/alert-rules -- same request/response shapes.

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 job's id, the channel's id, and the message style's id.
$jobId = 214
$alertChannelId = 5
$messageStyleId = 3

# Step 3: Create the rule -- notify on Failed (run status code 8). (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newRule = @{ AlertChannelId = $alertChannelId; TriggerOnRunStatusCode = 8; MessageStyleId = $messageStyleId; AlertScheduleId = $null } | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$jobId/alert-rules" `
    -Method Post -Body $newRule -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Created rule id: $($created.id)"

# List every rule on the job.
$rules = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/jobs/$jobId/alert-rules" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$rules | ForEach-Object { "$($_.jobAlertRuleId): on $($_.runStatusName) -> $($_.channelName) using '$($_.styleName)'" }

# Delete it later.
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/alert-rules/$($created.id)" -Method Delete -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

TriggerOnRunStatusCode

Any dbo.RunStatus code, though the Console UI today only offers 6 (Succeeded) and 8 (Failed).

What you get back

POST -- 201 Created:

{ "id": 14 }

GET -- 200 OK, an array:

[ { "jobAlertRuleId": 14, "triggerOnRunStatusCode": 8, "runStatusName": "Failed", "alertChannelId": 5, "channelName": "DBA Team Slack", "messageStyleId": 3, "styleName": "Standard Failure", "alertScheduleId": null, "scheduleName": null, "isActive": true } ]

DELETE -- 204 No Content -- no body.

Codes this call can return

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

  • 201 -- created.
  • 200 -- the list.
  • 204 -- deleted.
  • 400 -- (create) that exact job/step + status + channel combination already has a rule.
  • 403 -- you don't have Job.View/Job.Edit on the job or step.
  • 404 -- (delete) no rule exists with that id.

What gets audited

Create is recorded as JobAlertRule / Create Alert Rule; delete as JobAlertRule / Delete Alert Rule. The list GET isn't audited.

See also: List Alert Channels, Manage Message Styles, Manage Alert Schedules.