Returns a snapshot of this install's own view of the fleet -- whether it's the master, the master's address, and which peers it knows about. This is a point-in-time read of whatever this box's own Fleet.SyncPeer table has, not a live cross-fleet query -- there's no live propagation between fleet members yet (see the caveat in Manage Job Sync Groups), so a peer's own topology view can be stale relative to this one.

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. Request the topology.

The call

GET /api/fleet/topology

No route parameters, no query parameters, no request body.

Permission needed: none beyond being authenticated -- it only reveals server names and addresses, the same reasoning as Calling the API From Your Own Code's /api/security/me.

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: Request the topology.
var topology = await client.GetFromJsonAsync<FleetTopologyResponse>("/api/fleet/topology", jsonOptions);
Console.WriteLine($"Is master: {topology!.IsMaster}, fleet: {topology.FleetName}");
foreach (var peer in topology.Peers)
    Console.WriteLine($"  peer: {peer.PeerName} ({peer.ApiBaseUrl})");

record FleetPeerSummary(string PeerName, string ApiBaseUrl);
record FleetTopologyResponse(bool IsMaster, string? FleetName, string? MasterApiUrl, FleetPeerSummary[] Peers);

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: Request the topology. (-AllowUnencryptedAuthentication: PowerShell requires this for Windows auth over plain http to anything but localhost -- see "Network Access & Authentication Security".)
$topology = Invoke-RestMethod -Uri "http://your-minion-agent-server:5443/api/fleet/topology" -UseDefaultCredentials -AllowUnencryptedAuthentication -Headers $headers
"Is master: $($topology.isMaster), fleet: $($topology.fleetName)"
$topology.peers | ForEach-Object { "  peer: $($_.peerName) ($($_.apiBaseUrl))" }

What you get back

200 OK:

{ "isMaster": true, "fleetName": "Corp Fleet", "masterApiUrl": null, "peers": [ { "peerName": "DR-SITE", "apiBaseUrl": "https://dr-minion-agent:5001" } ] }

If this install isn't part of a fleet at all, you get { "isMaster": false, "fleetName": null, "masterApiUrl": null, "peers": [] } rather than an error.

Codes this call can return

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

  • 200 -- always, even for a standalone install.
  • 401 -- no valid authentication at all.

Not audited -- it's a read-only status check.

See also: Manage Sync Peers, Manage Job Sync Groups.