API & Route Contract â
Hermes-Relay crosses three independent server surfaces. They may run on the same machine, but they do not share a base URL, authentication model, or owner. Use this page to choose the right contract before reaching for an endpoint.
Authorization: Bearer API_SERVER_KEYUPSTREAM · :9119Dashboard & GatewayPreferred chat, Manage, profiles, Vanilla Hermes voice and inbound files.Dashboard session + WS ticketOPTIONAL PLUGIN · :8767Hermes RelayPairing, terminal, media enhancements, Relay voice, desktop tools and phone control.Relay session + per-channel grantsKeep credentials in their lane
A dashboard cookie is not an API key. An API bearer is not a Relay session. Relay accepts the Hermes API bearer only on its explicitly documented voice routes; all other protected Relay routes require pairing and the appropriate session grant.
Ownership at a glance â
| Surface | Owner | Base URL | Primary authentication | Relay required? |
|---|---|---|---|---|
| API Server | Upstream Hermes | http(s)://host:8642 | Required API_SERVER_KEY bearer when the API server is enabled | No |
| Dashboard / Gateway | Upstream Hermes | http(s)://host:9119 | Dashboard session; short-lived WS ticket for /api/ws | No |
| Relay | Hermes-Relay plugin | ws(s)://host:8767 and matching HTTP(S) origin | Pairing code, then Relay session token and grants | Yes |
| Compatibility hook | Hermes-Relay plugin, older hosts only | Injected into the API server | Same auth as the host API server | No, but non-upstream |
Client routing contract â
Hermes-Relay chooses routes by capability and authentication state:
- Probe API-server
GET /v1/capabilities. - If Manage authentication is ready, obtain a dashboard WS ticket and prefer
/api/wsfor chat with live reasoning. - Otherwise use native
/api/sessions/{id}/chat/streamover SSE. - Fall back to
/v1/chat/completionsor/v1/runsonly when the native session surface is unavailable. - Use dashboard
/api/audio/*for Vanilla Hermes voice. - Use Dashboard file download/stream routes for ordinary inbound media.
- Contact Relay only for paired, additive tools and enhancements.
Chat, Manage, Vanilla Hermes voice, and ordinary inbound files must continue to work against an unmodified upstream Hermes installation. Relay routes never become a hidden dependency for that default path.
Contract labels â
The reference uses these labels consistently:
| Label | Meaning |
|---|---|
| Upstream | Owned and served by unmodified Hermes Agent |
| Relay | Owned by the optional Hermes-Relay plugin/server |
| Loopback | Callable only from the Hermes host |
| Paired | Requires a Relay session token and the named grant |
| Sideload | Requires the Android sideload build; Google Play fails closed |
| Experimental | Wire shape or behavior may change between minor releases |
| Compatibility | Older-host fallback; never the preferred native path |
Reference map â
- Upstream Hermes contract â API Server, Dashboard and Gateway routes consumed by Hermes-Relay.
- Relay API contract â route families, grants, loopback boundaries and build-flavor gates.
- Relay server operations â deployment, environment, complete route detail and troubleshooting.
- Compatibility contract â optional older-host routes, feature detection and removal.
- Configuration â client and server settings.
Source of truth â
GET /v1/capabilities is authoritative for a running Hermes API Server. Relay routes are registered in plugin/relay/server.py. The public reference records only surfaces Hermes-Relay consumes or exposes; it is not a complete reference for every endpoint in the Hermes dashboard.