Skip to content

Hermes Bridge API

One HTTP API. Every client. Full Hermes.

The Hermes Web UI is not just a web app — it is a thin client over a complete, self-hosted HTTP API. Everything the web interface can do (stream a conversation, switch models, browse the workspace, run git, schedule cron jobs, manage memory and skills, transcribe voice) is a documented endpoint on your own server. The web UI simply calls them.

That means any client can be a first-class Hermes client. An iOS app, an Android app, an iPad app, a CLI, a Raycast extension, a home-screen widget, another service — they all speak the same HTTP + Server-Sent Events protocol and get the same full-fidelity access to your agent. There is no proprietary gateway, no per-platform backend, no vendor lock: point a client at https://your-hermes-host/ and it has the whole surface.

This documentation is the contract for that bridge. It is written so a developer with no prior knowledge of Hermes internals can build a native app at feature parity with the web UI from this spec alone. Every endpoint here is one a real client needs — the reference iOS client hermex is built entirely on it.

What "bridge API" means

┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  Web UI     │   │  iOS app    │   │ Android app │   │  Your app   │
│ (bundled)   │   │  (hermex)   │   │  (future)   │   │  (anything) │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                 │                 │
       └────────────┬────┴─────────────────┴─────────────────┘
                    │   HTTP + Server-Sent Events (this API)
            ┌───────▼─────────────────────────────────┐
            │         Hermes Web UI server             │
            │   (your host — you run it, you own it)   │
            └───────┬─────────────────────────────────┘
                    │
            ┌───────▼─────────┐
            │  Hermes Agent   │  models · memory · skills · tools · cron
            └─────────────────┘

The server is the bridge. It exposes the agent's full capability as a stable HTTP surface. Clients are interchangeable — the web UI has no privileged access a third-party app can't also have.

Why it matters

  • Build once per platform, not once per feature. The protocol is complete and stable. A native app implements the endpoints it needs and gets streaming chat, session management, workspace/git, cron, memory, skills, and voice — no server changes required.
  • Self-hosted and sovereign. The API lives on the host you run. No third-party relay sees your conversations. Your app talks directly to your server.
  • Real-time by design. Live assistant responses, tool calls, approvals, and clarifications stream over SSE — a native client shows the same live typing the web UI does.
  • One auth story. A single password (or a reverse-proxy header) unlocks the whole surface for every client.

Start here

Guide What it covers
Getting started Connect, authenticate, and make your first call in ~10 lines
Authentication Password login, the session cookie, custom headers for proxied deployments
Streaming (SSE) The real-time protocol — how live chat, approvals, and clarifications work
Conventions Base URL, headers, session IDs, error shapes, pagination

Endpoint reference

Category Endpoints What a client builds with it
Sessions & projects list, detail, create, rename, pin, archive, branch, compress, undo, retry, move the conversation sidebar + lifecycle
Chat & streaming start, stream (SSE), steer, cancel, goal, background the live chat surface — the crown jewel
Approvals & clarify pending, stream (SSE), respond tool-approval + agent-question prompts
Models, providers & personas models, providers, default-model, reasoning, personalities the model/provider pickers
Profiles & settings profiles, switch, active, settings multi-profile switching + preferences
Memory read, write the memory management screen
Skills list, content the skills browser
Commands slash-command catalog the composer's / menu
Workspace, files & git list, file, upload, git status/diff/commit/push the workspace explorer + source control
Cron / scheduled jobs list, create, update, run, pause, output the scheduled-tasks panel
Voice transcribe, tts push-to-talk + spoken replies
Insights & updates insights, updates/check, updates/apply usage stats + self-update

Full index: every endpoint on one page.

This is the client-facing bridge surface — the endpoints a native app needs to reach parity with the web UI. Internal/admin/plumbing endpoints (health probes, CSP reports, client-event logging, kanban internals) are intentionally omitted; they are not part of the client contract.