Attaches a tag to a step, creating the tag first if the name doesn't already exist -- same mechanics as Tag a Job, just scoped to one step. There's no untag call -- removing a tag from a step isn't possible through the API today.

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. Send the tag name (and optionally a color, if this might be a brand-new tag).

The call

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

Permission needed: Job.Edit 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: Send the tag name. Color only matters if this tag doesn't exist yet.
var tag = new AddTagRequest(TagName: "critical", Color: "#e67e22");
var response = await client.PostAsJsonAsync($"/api/job-steps/{jobStepId}/tags", tag, jsonOptions);
response.EnsureSuccessStatusCode();
Console.WriteLine("Tagged.");

record AddTagRequest(string TagName, string? Color);

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

# Step 3: Send the tag name. Color only matters if this tag doesn't exist yet. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$body = @{ TagName = "critical"; Color = "#e67e22" } | ConvertTo-Json
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/job-steps/$jobStepId/tags" `
    -Method Post -Body $body -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Tagged."

What you get back

204 No Content -- no body.

Codes this call can return

See API Response Codes for what each one means in general. For this specific call:

  • 204 -- tagged (whether the tag already existed or was just created).
  • 403 -- you don't have Job.Edit on this step.

See also: List a Job's Steps (its tags/inheritedTags fields show what's on each step), List Tags, Tag a Job.