Registers another Minion Agent install as a peer this fleet can reference in a Job Sync Group. A peer is just a name, a base API URL, and the credential used to authenticate to it -- registering one doesn't connect to it or verify it's reachable.

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 credential id the peer will authenticate with (from List Credentials).
  3. Register, update, or remove the peer.

The calls

GET    /api/sync-peers
POST   /api/sync-peers
PUT    /api/sync-peers/{syncPeerId}
DELETE /api/sync-peers/{syncPeerId}

Permission needed: Security.Manage for all four -- this is fleet topology/security setup, not a per-job concern.

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 credential id the peer authenticates with.
var credentialId = 4;

// Step 3: Register the peer.
var newPeer = new CreateSyncPeerRequest(PeerName: "DR-SITE", ApiBaseUrl: "https://dr-minion-agent:5001", CredentialId: credentialId);
var response = await client.PostAsJsonAsync("/api/sync-peers", newPeer, jsonOptions);
response.EnsureSuccessStatusCode();
var created = await response.Content.ReadFromJsonAsync<CreatedIdResponse>(jsonOptions);
Console.WriteLine($"Created sync peer id: {created!.Id}");

// List every registered peer.
var peers = await client.GetFromJsonAsync<SyncPeerSummary[]>("/api/sync-peers", jsonOptions);
foreach (var peer in peers!)
    Console.WriteLine($"{peer.SyncPeerId}: {peer.PeerName} ({peer.ApiBaseUrl}), credential = {peer.CredentialName}, active = {peer.IsActive}");

// Remove a peer.
var deleteResponse = await client.DeleteAsync($"/api/sync-peers/{created.Id}");
deleteResponse.EnsureSuccessStatusCode();

record CreateSyncPeerRequest(string PeerName, string ApiBaseUrl, int CredentialId);
record CreatedIdResponse(int Id);
record SyncPeerSummary(int SyncPeerId, string PeerName, string ApiBaseUrl, int CredentialId, string CredentialName, Guid? PeerFleetId, 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 credential id the peer authenticates with.
$credentialId = 4

# Step 3: Register the peer. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$newPeer = @{ PeerName = "DR-SITE"; ApiBaseUrl = "https://dr-minion-agent:5001"; CredentialId = $credentialId } | ConvertTo-Json
$created = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/sync-peers" `
    -Method Post -Body $newPeer -ContentType "application/json" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Created sync peer id: $($created.id)"

# List every registered peer.
$peers = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/sync-peers" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
$peers | ForEach-Object { "$($_.syncPeerId): $($_.peerName) ($($_.apiBaseUrl)), credential = $($_.credentialName), active = $($_.isActive)" }

# Remove a peer.
Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/sync-peers/$($created.id)" -Method Delete -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers

PUT /api/sync-peers/{syncPeerId} takes the same body shape as POST, and replaces the peer's name/URL/credential wholesale.

What you get back

POST -- 201 Created:

{ "id": 3 }

GET -- 200 OK, an array:

[
    { "syncPeerId": 3, "peerName": "DR-SITE", "apiBaseUrl": "https://dr-minion-agent:5001", "credentialId": 4, "credentialName": "Fleet Sync Account", "peerFleetId": null, "isActive": true }
]

PUT/DELETE -- 204 No Content -- no body.

Codes this call can return

See API Response Codes for what each one means in general. For these calls:

  • 201 -- peer created.
  • 200 -- the list.
  • 204 -- updated or deleted.
  • 403 -- you don't have Security.Manage.

None of the four endpoints do a pre-check for "is this peer still referenced by a sync group" before delete -- unlike deleting the group itself (see Manage Job Sync Groups), which does refuse if jobs still depend on it.

What gets audited

Create/update/delete are each recorded as SyncPeer / Create Sync Peer, Alter Sync Peer, Delete Sync Peer. The list GET isn't audited.

See also: List Credentials, Manage Job Sync Groups, Get Fleet Topology.