API overview
The two HTTP APIs: the gateway for inference and the control plane API for administration.
Wingsmith exposes two HTTP APIs on different hosts, for different callers. Pick the one that matches what you are doing.
Gateway (inference)
OpenAI-compatible requests to a served model. Called by applications with a tenant key, or by your own edge on the internal listener.
Control plane (administration)
Clusters, deployments, endpoints, tenants and everything else you manage. Called by the console, hgr and your own automation.
| Gateway | Control plane | |
|---|---|---|
| Process | hangar-gateway | the plane |
| Purpose | Run inference | Declare and observe state |
| Shape | OpenAI formats | JSON with list envelopes, see Conventions |
| Credential | Tenant key (hgrk1...) on the public listener, none on the internal one | Session token from POST /v1/auth/login |
| Reference | Calling the gateway | Authentication, then the generated endpoint pages |
Both use paths under /v1, but they are different servers. A tenant key does not work on the control plane, and a session token does not work on the gateway.
Control plane API
The console and hgr are both clients of this API, so anything they do you can do over HTTP. All routes are under /v1. There is no version in the hostname, and bodies are UTF-8 JSON only.
curl https://plane.example.com/v1/clusters \
-H "Authorization: Bearer $HGR_ACCESS_TOKEN"
Routes follow REST conventions: GET /v1/clusters lists, GET /v1/clusters/{ref} reads one, POST creates, PATCH updates and DELETE removes. Most collections take filters as query parameters.
Read these first:
- Authentication: getting and refreshing a session, and which credential reaches which route.
- Conventions: envelopes, errors, pagination, identifiers, idempotency and conditional updates.
The plane publishes its machine-readable schema at /schema. The generated endpoint pages in this tab come from that schema. Where a client disagrees with it, the client is wrong.
What the control plane does not expose
- No cluster
api_endpoint. The operator dials out and its credential is its identity, so an address would add nothing. The one address a cluster carries isserving, which only the gateway dials. - No Kubernetes-specific fields. No kubelet versions, manifest fragments or object references. Only the operator knows Kubernetes exists.
- No telemetry on an object. Utilization, temperature, throughput, latency and token counts are never fields on a device, node or deployment. Health, allocation, membership and residency are state and live here. Measurements are read back under
/v1/metrics.
The plane never talks to a cluster over this API. Operators sync over a separate WebSocket protocol; see Wire protocol.