Turns a target server on or off. A deactivated server is refused at run time -- any job or ad-hoc step run resolving to it is blocked. This is the only lifecycle control for a target server; there's no delete.

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 target server's id (from List Target Servers).
  3. Send the new active state.

The call

PATCH /api/target-servers/{targetServerId}/active

Permission needed: TargetServer.Manage.

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 target server's id (from List Target Servers).
var targetServerId = 7;

// Step 3: Send the new active state.
var response = await client.PatchAsJsonAsync($"/api/target-servers/{targetServerId}/active", new SetActiveRequest(IsActive: false), jsonOptions);
response.EnsureSuccessStatusCode();
Console.WriteLine("Updated.");

record SetActiveRequest(bool IsActive);

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 target server's id (from List Target Servers).
$targetServerId = 7

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

"Updated."

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 -- updated.
  • 403 -- you don't have TargetServer.Manage.
  • 404 -- no target server exists with that id (unlike most PATCH toggles elsewhere in this API, this one does check).

See also: List Target Servers, Register a Target Server.