An append-only log of notes on a step -- troubleshooting history, documentation, anything worth remembering. There's no edit or delete; only list and add.

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 step's id.
  3. List the existing comments, or add a new one.

List comments

GET /api/job-steps/{jobStepId}/comments

Permission needed: Job.View on this step.

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 jobStepId (from List a Job's Steps).
var jobStepId = 214;

// Step 3: List the existing comments.
var comments = await client.GetFromJsonAsync<CommentInfo[]>($"/api/job-steps/{jobStepId}/comments", jsonOptions);
foreach (var comment in comments!)
{
    Console.WriteLine($"[{comment.CreatedAt}] {comment.CreatedBy}: {comment.CommentText}");
}

record CommentInfo(int CommentID, string CommentText, string CreatedBy, DateTime CreatedAt);

PowerShell example

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

# Step 2: You already have the jobStepId (from List a Job's Steps).
$jobStepId = 214

# Step 3: List the existing comments. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$comments = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/job-steps/$jobStepId/comments" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$comments | ForEach-Object { "[$($_.createdAt)] $($_.createdBy): $($_.commentText)" }

What you get back

200 OK, an array:

[ { "commentID": 4, "commentText": "Switched to a retry loop after intermittent timeouts.", "createdBy": "jdoe", "createdAt": "2026-08-12T09:00:00Z" } ]

Add a comment

POST /api/job-steps/{jobStepId}/comments

Permission needed: Job.Edit on this step.

C# example

// Step 1: Authenticate (same client setup as above).
// Step 2: You already have the jobStepId.
// Step 3: Add a comment.
var comment = new AddCommentRequest(CommentText: "Switched to a retry loop after intermittent timeouts.", CreatedBy: "jdoe");
var response = await client.PostAsJsonAsync($"/api/job-steps/{jobStepId}/comments", comment, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedComment>(jsonOptions);
Console.WriteLine($"Comment id: {created!.JobStepCommentID}");

record AddCommentRequest(string CommentText, string CreatedBy);
record CreatedComment(int JobStepCommentID);

PowerShell example

# Step 1: Authenticate (same headers as above).
# Step 2: You already have the jobStepId.
# Step 3: Add a comment.
$body = @{ CommentText = "Switched to a retry loop after intermittent timeouts."; CreatedBy = "jdoe" } | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/job-steps/$jobStepId/comments" `
    -Method Post -Body $body -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Comment id: $($created.jobStepCommentID)"

What you get back

201 Created: { "JobStepCommentID": 5 }.

Codes these calls can return

See API Response Codes for what each one means in general.

  • 200 -- (list) the comments, even if there are none.
  • 201 -- (add) created.
  • 403 -- you don't have Job.View/Job.Edit on this step.

See also: List a Job's Steps.