---
title: OpenLM Router API reference
description: "The OpenLM Router REST endpoints used for failover in OpenLM Platform deployments: what each one returns and how to read it."
product: OpenLM Platform
---

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:

```text
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.

:::warning[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](https://www.openlm.com/documentation/cloud/deployment-operations/router/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`:

```json
{
  "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:

```json
"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](https://www.openlm.com/documentation/cloud/deployment-operations/router/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](https://www.openlm.com/documentation/cloud/deployment-operations/router/operations)
- [Troubleshoot OpenLM Router](https://www.openlm.com/documentation/cloud/deployment-operations/router/troubleshooting)