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
| Request | Access | Purpose |
|---|---|---|
GET /health, /health/live, /health/ready, /health/startup | No token | Probes and the overall state, with the licence detail |
GET /metrics | No token | Prometheus metrics |
GET /openapi.json, /openapi.yaml, /.well-known/openapi | No token | The OpenAPI document of every connected endpoint |
GET /api/v1/router/instances | Scope router:routing:read | Connected instances |
GET /api/v1/router/endpoints | Scope router:routing:read | The distinct Endpoints, as the licence monitor counts them |
GET /api/v1/router/routing/weights | Scope router:routing:read | Weight overrides and effective weights |
POST /api/v1/router/routing/weights | Scope router:routing:write | Set a weight override |
POST /api/v1/gateway/administration/router/resync | Scope router:routing:write | Ask 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.
| Caller | Answer |
|---|---|
| No token, or a token the gateway does not accept | 401, empty body, WWW-Authenticate: Bearer |
| A valid token without the scope | 403, empty body |
The administration answers are JSON with camel-case property names. Enumerations are written as numbers:
transportType | Transport |
|---|---|
0 | InMemory |
1 | UDP |
2 | TCP |
3 | TLS |
4 | RabbitMQ |
5 | Messaging |
status | Instance health |
|---|---|
0 | Unknown |
1 | Healthy |
2 | Degraded |
3 | Draining |
4 | Unhealthy |
A request the gateway refuses for its content gets 400 with { "error": "<code>", "message": "<text>" }.
Health
| Path | 200 when | Otherwise | status in the body |
|---|---|---|---|
/health/live | Always | live | |
/health/ready | The gateway has started, its transports are ready, and every service in Gateway:Health:RequiredMicroservices has a healthy or degraded instance | 503 | ready |
/health/startup | The gateway has started | 503 | startup |
/health | Always | ok |
curl -s https://gateway.contoso.example/health/ready
The body, application/json:
| Property | Meaning |
|---|---|
status | As in the table above |
started | The gateway has finished starting |
ready | The value /health/ready answers with |
transportReady | The transports accept connections |
requiredMicroservices | Gateway:Health:RequiredMicroservices, in lower case, without :port and without the endings in Gateway:Health:ServiceNameSuffixes |
missingMicroservices | The required services without a healthy or degraded instance |
traceId | The request’s trace identifier |
licence | The 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.
| Metric | Type | Labels | Meaning |
|---|---|---|---|
gateway_active_connections | gauge | Connected instances | |
gateway_registered_endpoints | gauge | Endpoints summed over the instances: an endpoint counts once per instance | |
stella_router_routing_weight | gauge | service, version, instance_id, source | The effective weight of each instance; source is instanceOverride, versionOverride or instance |
stella_router_requests_total | counter | service, version, instance_id, status_class | Requests the gateway sent to a service; status_class is 1xx to 5xx |
stella_router_request_duration_seconds | histogram | service, version, instance_id | Their duration; buckets from 0.005 to 10 seconds |
stellaops_router_licence_endpoints | gauge | status | The 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):
| Path | Content |
|---|---|
/openapi.json | The document, application/json |
/openapi.yaml | The same document, application/yaml |
/.well-known/openapi | Links 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
}
]
}
| Property | Meaning |
|---|---|
group | individual 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 |
method | The method of an individual Endpoint; null for the other groups |
template | The path template as it is compared: each parameter becomes {} |
registeredMethods, registeredTemplates | What the services registered |
services | The services that register it |
instances | The 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 }
| Field | Required | Meaning |
|---|---|---|
service | Yes | The service name |
version | Yes | The service version |
instanceId | No | One instance; without it, the override applies to every instance of the version |
weight | Yes | 0 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" }
]
}
- An instance override wins over a version override, which wins over the instance’s own weight. Setting the same service, version and instance again replaces the override.
- Overrides live in the memory of one gateway process: they apply to that gateway only and are lost when it restarts.
- Weights decide only between instances that tie on ping and heartbeat (Several instances and regions).
| Refusal | error |
|---|---|
| No body | invalid_request |
No service | invalid_service |
No version | invalid_version |
weight below 0 or above 1000 | invalid_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" }
| Field | Meaning |
|---|---|
connectionId | One connection, exactly as the instance list shows it; leave it out to ask every connection |
reason | Text 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 }
| Status | When |
|---|---|
200 | At least one connection matched |
404 | No connection matched (same body, matchedCount 0) |
400 invalid_connection_id | connectionId is present but empty |
