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.

UPSTREAM · :8642Hermes API ServerChat fallback, sessions, capabilities, skills and toolsets.Authorization: Bearer API_SERVER_KEYUPSTREAM · :9119Dashboard & GatewayPreferred chat transport, Manage, profiles and Vanilla Hermes voice.Dashboard session + WS ticketOPTIONAL PLUGIN · :8767Hermes RelayPairing, terminal, media, Relay voice, desktop tools and phone control.Relay session + per-channel grants

Keep 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	Optional API_SERVER_KEY bearer	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:

1. Probe API-server GET /v1/capabilities.
2. If Manage authentication is ready, obtain a dashboard WS ticket and prefer /api/ws for chat with live reasoning.
3. Otherwise use native /api/sessions/{id}/chat/stream over SSE.
4. Fall back to /v1/chat/completions or /v1/runs only when the native session surface is unavailable.
5. Use dashboard /api/audio/* for Vanilla Hermes voice.
6. Contact Relay only for paired, additive power features.

Chat, Manage, and Vanilla Hermes voice 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.