Registers a new SQL Server as a target -- nothing can be pointed at a server (a job's target, a step's target, a credential's scope) until it's registered here first. There's no update endpoint for a target server's fields once created, and no delete -- Activate/Deactivate is the only lifecycle control.

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. Send the new server's details.

The call

POST /api/target-servers

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: Send the new server's details.
var newServer = new CreateTargetServerRequest(ServerName: "SQLPROD02", HostName: "sqlprod02.internal.example.com", Description: "Reporting replica");
var response = await client.PostAsJsonAsync("/api/target-servers", newServer, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedId>(jsonOptions);
Console.WriteLine($"Created target server id: {created!.Id}");

record CreateTargetServerRequest(string ServerName, string HostName, string? Description);
record CreatedId(int Id);

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: Send the new server's details. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newServer = @{ ServerName = "SQLPROD02"; HostName = "sqlprod02.internal.example.com"; Description = "Reporting replica" } | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/target-servers" `
    -Method Post -Body $newServer -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

"Created target server id: $($created.id)"

What you get back

201 Created:

{ "Id": 11 }

A newly-registered server is active by default.

Codes this call can return

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

  • 201 -- created.
  • 403 -- you don't have TargetServer.Manage.

A duplicate ServerName isn't specially handled by this endpoint.

See also: List Target Servers, Activate/Deactivate a Target Server.