OpenLM Router API reference

Use this page to script an OpenLM Router installation or to find out what a response means. Everything here is also available from the Router itself, and the pages in this section show each call in the task it belongs to.

API browser of the Router

Every Router serves an interactive reference, generated from the running build, at:

http://<router-host>:8100/swagger

Use it for request and response schemas. It cannot go stale the way a written page can. The following table is a map of the endpoints that matter for failover, not a replacement for it.

Keep these ports on your administration network

Ports 8100 and 8101 are administration interfaces. Allow access to them only from your administration network, and do not publish them to the internet. Publish only the license ports your clients use. See System requirements.

Failover endpoints

The following table lists the failover endpoints and what each one does:

Method	Path	What it does
GET	/api/v1/status	The state of every pair: which server it is serving from, the health of both servers, and recent failovers. configurationManagement reports the routerId of this Router and its last sync with OpenLM Platform.
GET	/api/v1/config	The routing configuration the Router collected from OpenLM Platform. Read-only: you change the configuration in OpenLM Platform.
GET	/api/v1/platform/servers	The license servers from the OpenLM Platform snapshot, and the source of every serverId. Answers 503 until a snapshot exists.
GET	/api/v1/admission-controller/platform-credentials	Reads back the stored OpenLM Platform connection. The secret is masked.
PUT	/api/v1/admission-controller/platform-credentials	Stores the OpenLM Platform connection.
POST	/api/v1/admission-controller/platform-credentials/check-connection	Tests the credential in the body. If clientSecret is empty or ***, tests the stored credential instead.
POST	/api/v1/failover/manual	Moves a pair to its backup. Takes pairId and an optional message for the history.
POST	/api/v1/failback	Returns a pair to its primary.
GET	/readyz	Readiness with detail: which ports are bound against which are wanted. Answers 503 until the Router has collected its configuration.
GET	/health/ready, /health/live, /health/start	The standard OpenLM health envelope.

The Router exposes further endpoints for features outside failover. They are not covered here and are not needed for a failover deployment.

Read the responses

The following sections explain how to read the main responses of the Router.

Confirm a configuration took effect

To tell an unapplied configuration from a networking problem, call /readyz:

{
  "appliedGeneration": 1,
  "latestGeneration": 1,
  "boundPorts": [27000],
  "desiredPorts": [27000],
  "failoverRoleConverged": true
}

boundPorts matching desiredPorts means every pair's listen port is open. A port in desiredPorts but not in boundPorts is a pair that was accepted but whose port could not be opened, usually because another process already holds it.

When appliedGeneration lags latestGeneration, a configuration change has been accepted but not applied. It catches up within seconds.

Recognize the results

The following table lists responses and what they mean:

Response	What it means
503 from /api/v1/platform/servers	No OpenLM Platform sync has succeeded, or none for 10 minutes. On a new deployment, the OpenLM Platform connection is not working. On a Router that was working, either the sync is failing, as lastFailure in /api/v1/status shows, or the Router lost its job schedule and needs restarting.
200 from check-connection with "status": "Failed"	A rejected credential. This endpoint reports its verdict in the body, so check status rather than the HTTP code.
409 "Already on backup" from /api/v1/failover/manual	The pair is on its backup, the pairId does not exist, or the pair has no backup. The Router answers the same way for all three. Confirm the name and the backup against /api/v1/config before concluding the pair has already moved.

Check the sync with OpenLM Platform

To check whether the Router is collecting its configuration from OpenLM Platform, read the configurationManagement block of GET /api/v1/status. Before the OpenLM Platform connection is configured, it reads:

"configurationManagement": {
  "shape": "serviceManaged",
  "routerId": "15ec9751-826b-44ab-a313-43441b9eaed5",
  "lastSync": {
    "lastSuccessfulSync": null,
    "lastAppliedConfigVersion": null,
    "lastFailure": "No Platform connection is configured, so the Router has no address for the LicOps Configuration service",
    "lastFailureAt": "2026-10-05T08:21:31.4659468Z"
  }
}

The following table describes the fields in this block. For help with a failing sync, see Troubleshooting.

Field	What it shows
routerId	How OpenLM Platform identifies this Router. It is created on the first start and stored in MongoDB.
lastSuccessfulSync	When the Router last synced with OpenLM Platform. If it is not advancing, the Router is not talking to OpenLM Platform.
lastAppliedConfigVersion	The version of the OpenLM Platform configuration this Router is running.
lastFailure, lastFailureAt	The current sync problem and when it started. A successful sync clears both, so anything here is live, not history.

Related

• Operate OpenLM Router
• Troubleshoot OpenLM Router