Gateway HTTP API

Besides the endpoints of your services, the Router gateway host answers a small HTTP API of its own: health, metrics, the OpenAPI document of the connected services, and administration of instances, Endpoints and routing weights. This page lists each request with its access rule, its parameters and its answers, so you can wire probes, dashboards and operator scripts to it.

The examples call a gateway at https://gateway.contoso.example. An administration request carries the header Authorization: Bearer <token> with a token that has the scope named below.

Overview

RequestAccessPurpose
GET /health, /health/live, /health/ready, /health/startupNo tokenProbes and the overall state, with the licence detail
GET /metricsNo tokenPrometheus metrics
GET /openapi.json, /openapi.yaml, /.well-known/openapiNo tokenThe OpenAPI document of every connected endpoint
GET /api/v1/router/instancesScope router:routing:readConnected instances
GET /api/v1/router/endpointsScope router:routing:readThe distinct Endpoints, as the licence monitor counts them
GET /api/v1/router/routing/weightsScope router:routing:readWeight overrides and effective weights
POST /api/v1/router/routing/weightsScope router:routing:writeSet a weight override
POST /api/v1/gateway/administration/router/resyncScope router:routing:writeAsk instances to send their endpoints again

Keep the paths without a token off the public interface when they should not be public (Security).

Access to the administration requests

The administration requests need a JWT bearer token that the gateway accepts (Router gateway host) and that carries the scope in a scope or scp claim, as one value or a space-separated list. The scope must match exactly, in the same letter case.

CallerAnswer
No token, or a token the gateway does not accept401, empty body, WWW-Authenticate: Bearer
A valid token without the scope403, empty body

The administration answers are JSON with camel-case property names. Enumerations are written as numbers:

transportTypeTransport
0InMemory
1UDP
2TCP
3TLS
4RabbitMQ
5Messaging
statusInstance health
0Unknown
1Healthy
2Degraded
3Draining
4Unhealthy

A request the gateway refuses for its content gets 400 with { "error": "<code>", "message": "<text>" }.

Health

Path200 whenOtherwisestatus in the body
/health/liveAlwayslive
/health/readyThe gateway has started, its transports are ready, and every service in Gateway:Health:RequiredMicroservices has a healthy or degraded instance503ready
/health/startupThe gateway has started503startup
/healthAlwaysok
curl -s https://gateway.contoso.example/health/ready

The body, application/json:

PropertyMeaning
statusAs in the table above
startedThe gateway has finished starting
readyThe value /health/ready answers with
transportReadyThe transports accept connections
requiredMicroservicesGateway:Health:RequiredMicroservices, in lower case, without :port and without the endings in Gateway:Health:ServiceNameSuffixes
missingMicroservicesThe required services without a healthy or degraded instance
traceIdThe request’s trace identifier
licenceThe licence monitor’s last evaluation, informational only (Router licence)

A custom host can add sections of its own (Router gateway host). The health status code never depends on the licence. An excerpt of the licence object of a gateway with 13 Endpoints and no licence record; the full object also carries explanation, publishedAt, licenceFilesNotLoaded and installationIdConfigured, and its notice the licence record’s fields, null when no record applies:

{
  "evaluated": true,
  "status": "within-free-limit",
  "message": "Local Endpoint count: 13.",
  "endpoints": 13,
  "endpointsNoticeLevel": 250,
  "endpointsFreeLimit": 500,
  "endpointCountNote": "The displayed count is not conclusive.",
  "notice": {
    "case": "no-licence-file",
    "text": "No local licence record is loaded. See the applicable LICENSE and Order for permitted use. | component: router | status: within-free-limit",
    "licensee": null,
    "recordsInForce": 0
  },
  "licenceFilesLoaded": 0,
  "evaluatedAt": "2026-11-09T06:47:53Z",
  "informational": true
}

The monitor evaluates once a minute; before its first evaluation the object holds "evaluated": false and "informational": true.

Metrics

GET /metrics answers 200 with Content-Type: text/plain; version=0.0.4 in the Prometheus text format.

MetricTypeLabelsMeaning
gateway_active_connectionsgaugeConnected instances
gateway_registered_endpointsgaugeEndpoints summed over the instances: an endpoint counts once per instance
stella_router_routing_weightgaugeservice, version, instance_id, sourceThe effective weight of each instance; source is instanceOverride, versionOverride or instance
stella_router_requests_totalcounterservice, version, instance_id, status_classRequests the gateway sent to a service; status_class is 1xx to 5xx
stella_router_request_duration_secondshistogramservice, version, instance_idTheir duration; buckets from 0.005 to 10 seconds
stellaops_router_licence_endpointsgaugestatusThe licence monitor’s Endpoint count, with the licence status as label

The TLS transport’s certificate rejections are a .NET meter instrument, not part of this output (Deployment).

OpenAPI document

With Gateway:OpenApi:Enabled (the default), the gateway serves the OpenAPI 3.1.0 document of every connected endpoint (Schema validation and OpenAPI):

PathContent
/openapi.jsonThe document, application/json
/openapi.yamlThe same document, application/yaml
/.well-known/openapiLinks to both, with the current etag and generated_at

Both documents carry an ETag and Cache-Control: public, max-age=60. Send the ETag back in If-None-Match to get 304 Not Modified while the document is unchanged:

curl -s -D - -o openapi.json https://gateway.contoso.example/openapi.json
curl -s -o /dev/null -w "%{http_code}\n" https://gateway.contoso.example/openapi.json \
  -H 'If-None-Match: "<the ETag value>"'

Expected result: 200 and the document, then 304.

Instance list

GET /api/v1/router/instances lists every connected instance, ordered by service, version and instance. The optional query parameter service keeps the instances of one service, in any letter case; an unknown service gives an empty list.

Request: GET /api/v1/router/instances?service=inventory, with the bearer token. Answer:

{
  "instances": [
    {
      "service": "inventory",
      "version": "1.0.0",
      "instanceId": "inventory-01",
      "region": "demo",
      "connectionId": "...",
      "transportType": 2,
      "status": 1,
      "instanceWeight": 100,
      "effectiveWeight": 100,
      "source": "instance",
      "endpointCount": 4
    }
  ]
}

instanceWeight is the weight the instance announced, effectiveWeight the weight after overrides, and source where it comes from. endpointCount counts the instance’s own endpoints; do not add these up to get the licence count.

Endpoint list

GET /api/v1/router/endpoints lists the distinct Endpoints of every connected service, as the licence monitor counts them (Router licence).

Request: GET /api/v1/router/endpoints, with the bearer token. Answer:

{
  "count": 13,
  "countNote": "The displayed count is not conclusive.",
  "endpoints": [
    {
      "group": "individual",
      "method": "GET",
      "template": "/invoices/{}",
      "registeredMethods": ["GET"],
      "registeredTemplates": ["/invoices/{id}"],
      "services": ["billing"],
      "instances": 1
    }
  ]
}
PropertyMeaning
groupindividual for GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS and TRACE; extension for every other method, PATCH included; any for an endpoint that accepts any method
methodThe method of an individual Endpoint; null for the other groups
templateThe path template as it is compared: each parameter becomes {}
registeredMethods, registeredTemplatesWhat the services registered
servicesThe services that register it
instancesThe connections that register it

Routing weights

GET /api/v1/router/routing/weights returns the overrides and the effective weight of every connected instance. POST sets one override and returns the same state.

Request: POST /api/v1/router/routing/weights, with the bearer token and Content-Type: application/json:

{ "service": "inventory", "version": "1.0.0", "instanceId": "inventory-02", "weight": 300 }
FieldRequiredMeaning
serviceYesThe service name
versionYesThe service version
instanceIdNoOne instance; without it, the override applies to every instance of the version
weightYes0 to 1000

Answer:

{
  "overrides": [
    { "service": "inventory", "version": "1.0.0", "instanceId": "inventory-02", "weight": 300 }
  ],
  "effectiveWeights": [
    { "service": "inventory", "version": "1.0.0", "instanceId": "inventory-01", "connectionId": "...",
      "instanceWeight": 100, "effectiveWeight": 100, "source": "instance" },
    { "service": "inventory", "version": "1.0.0", "instanceId": "inventory-02", "connectionId": "...",
      "instanceWeight": 100, "effectiveWeight": 300, "source": "instanceOverride" }
  ]
}
Refusalerror
No bodyinvalid_request
No serviceinvalid_service
No versioninvalid_version
weight below 0 or above 1000invalid_weight

Resync

POST /api/v1/gateway/administration/router/resync asks connected instances to send their endpoints again, for example after a gateway restart that some services have not noticed yet.

Request: POST /api/v1/gateway/administration/router/resync, with the bearer token and Content-Type: application/json:

{ "reason": "after maintenance" }
FieldMeaning
connectionIdOne connection, exactly as the instance list shows it; leave it out to ask every connection
reasonText for the log; administration-request when left out

The body may be left out entirely. The answer:

{ "connectionId": null, "reason": "after maintenance", "matchedCount": 7, "requestedCount": 7, "skippedCount": 0 }
StatusWhen
200At least one connection matched
404No connection matched (same body, matchedCount 0)
400 invalid_connection_idconnectionId is present but empty