Sets which SQL Server a step runs against, overriding the job's own default target server. Pass null to clear the override and fall back to the job's target server.

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 target server id.

The call

PATCH /api/job-steps/{jobStepId}/target-server

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 target server id (null clears the override).
var response = await client.PatchAsJsonAsync($"/api/job-steps/{jobStepId}/target-server", new SetTargetServerRequest(TargetServerId: 7), jsonOptions);
response.EnsureSuccessStatusCode();
Console.WriteLine("Updated.");

record SetTargetServerRequest(int? TargetServerId);

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 target server id (null clears the override). (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$body = @{ TargetServerId = 7 } | ConvertTo-Json
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/job-steps/$jobStepId/target-server" `
    -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 Job.Edit on this step.

This call doesn't check whether the step id or target server id actually exist -- a bad id for either still returns 204. It also doesn't run the command-blacklist re-check that saving the step's command text does.

See also: Set a Step's Credential, Update a Step.