Changes a tag's color -- this changes it everywhere that tag appears, on every job/step it's attached to, direct or inherited. There's no rename or delete for a tag anywhere in 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 tag's id (from List Tags).
  3. Send the new color.

The call

PUT /api/tags/{tagId}

Permission needed: Job.Edit (unscoped -- not tied to any specific job/folder).

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 tag's id (from List Tags).
var tagId = 5;

// Step 3: Send the new color.
var response = await client.PutAsJsonAsync($"/api/tags/{tagId}", new SetColorRequest(Color: "#2980b9"), jsonOptions);
response.EnsureSuccessStatusCode();
Console.WriteLine("Updated.");

record SetColorRequest(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 tag's id (from List Tags).
$tagId = 5

# Step 3: Send the new color. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$body = @{ Color = "#2980b9" } | ConvertTo-Json
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/tags/$tagId" `
    -Method Put -Body $body -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Updated."

What you get back

204 No Content -- no body. A nonexistent tagId still returns 204 rather than a 404.

Codes this call can return

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

  • 204 -- updated.
  • 403 -- you don't have Job.Edit.

See also: List Tags.