[Skip to main content](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server#__docusaurus_skipToContent_fallback) On this page The API server exposes hermes-agent as an OpenAI-compatible HTTP endpoint. Any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox, and hundreds more — can connect to hermes-agent and use it as a backend. Your agent handles requests with its full toolset (terminal, file operations, web search, memory, skills) and returns the final response. When streaming, tool progress indicators appear inline so frontends can show what the agent is doing. One backend covers models + tools Hermes itself needs a configured provider and tool backends for the API server to be useful. A [Nous Portal](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway) subscription handles both — 300+ models plus web/image/TTS/browser via the Tool Gateway. Run `hermes setup --portal` once before starting the API server and frontends like Open WebUI or LobeChat get a fully tool-equipped backend. ## Quick Start [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#quick-start "Direct link to Quick Start") ### 1\. Enable the API server [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#1-enable-the-api-server "Direct link to 1. Enable the API server") Add to `~/.hermes/.env`: ```bash API_SERVER_ENABLED=true API_SERVER_KEY=change-me-local-dev # Optional: only if a browser must call Hermes directly # API_SERVER_CORS_ORIGINS=http://localhost:3000 ``` ### 2\. Start the gateway [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#2-start-the-gateway "Direct link to 2. Start the gateway") ```bash hermes gateway ``` You'll see: ```text [API Server] API server listening on http://127.0.0.1:8642 ``` ### 3\. Connect a frontend [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#3-connect-a-frontend "Direct link to 3. Connect a frontend") Point any OpenAI-compatible client at `http://localhost:8642/v1`: ```bash # Test with curl curl http://localhost:8642/v1/chat/completions \ -H "Authorization: Bearer change-me-local-dev" \ -H "Content-Type: application/json" \ -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}' ``` Or connect Open WebUI, LobeChat, or any other frontend — see the [Open WebUI integration guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui) for step-by-step instructions. ## Endpoints [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#endpoints "Direct link to Endpoints") ### POST /v1/chat/completions [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#post-v1chatcompletions "Direct link to POST /v1/chat/completions") Standard OpenAI Chat Completions format. Stateless — the full conversation is included in each request via the `messages` array. **Request:** ```json { "model": "hermes-agent", "messages": [\ {"role": "system", "content": "You are a Python expert."},\ {"role": "user", "content": "Write a fibonacci function"}\ ], "stream": false } ``` **Response:** ```json { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1710000000, "model": "hermes-agent", "choices": [{\ "index": 0,\ "message": {"role": "assistant", "content": "Here's a fibonacci function..."},\ "finish_reason": "stop"\ }], "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250} } ``` **Inline image input:** user messages may send `content` as an array of `text` and `image_url` parts. Both remote `http(s)` URLs and `[IMAGE]..."}\ ]\ }\ ] } ``` Uploaded files (`input_file` / `file_id`) and non-image `data:` URLs return `400 unsupported_content_type`. #### Multi-turn with previous\_response\_id [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#multi-turn-with-previous_response_id "Direct link to Multi-turn with previous_response_id") Chain responses to maintain full context (including tool calls) across turns: ```json { "input": "Now show me the README", "previous_response_id": "resp_abc123" } ``` The server reconstructs the full conversation from the stored response chain — all previous tool calls and results are preserved. Chained requests also share the same session, so multi-turn conversations appear as a single entry in the dashboard and session history. #### Named conversations [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#named-conversations "Direct link to Named conversations") Use the `conversation` parameter instead of tracking response IDs: ```json {"input": "Hello", "conversation": "my-project"} {"input": "What's in src/?", "conversation": "my-project"} {"input": "Run the tests", "conversation": "my-project"} ``` The server automatically chains to the latest response in that conversation. Like the `/title` command for gateway sessions. ### GET /v1/responses/{id} [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-v1responsesid "Direct link to GET /v1/responses/{id}") Retrieve a previously stored response by ID. ### DELETE /v1/responses/{id} [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#delete-v1responsesid "Direct link to DELETE /v1/responses/{id}") Delete a stored response. ### GET /v1/models [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-v1models "Direct link to GET /v1/models") Lists the agent as an available model. The advertised model name defaults to the [profile](https://hermes-agent.nousresearch.com/docs/user-guide/profiles) name (or `hermes-agent` for the default profile). Required by most frontends for model discovery. ### GET /v1/capabilities [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-v1capabilities "Direct link to GET /v1/capabilities") Returns a machine-readable description of the API server's stable surface for external UIs, orchestrators, and plugin bridges. ```json { "object": "hermes.api_server.capabilities", "platform": "hermes-agent", "model": "hermes-agent", "auth": {"type": "bearer", "required": true}, "features": { "chat_completions": true, "responses_api": true, "run_submission": true, "run_status": true, "run_events_sse": true, "run_stop": true } } ``` Use this endpoint when integrating dashboards, browser UIs, or control planes so they can discover whether the running Hermes version supports runs, streaming, cancellation, and session continuity without depending on private Python internals. ### GET /health [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-health "Direct link to GET /health") Health check. Returns `{"status": "ok"}`. Also available at **GET /v1/health** for OpenAI-compatible clients that expect the `/v1/` prefix. ### GET /health/detailed [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-healthdetailed "Direct link to GET /health/detailed") Authenticated readiness check for monitoring and control planes. It reports bounded status for the active profile's config, state database, configured model, disk space, gateway/platform state, active API runs, pending process completions, and active delegations. The response exposes status and counts, not config values, credentials, paths, commands, queue payloads, or raw errors. The public `/health` route remains a cheap liveness probe and does not run readiness checks. A degraded readiness result still uses HTTP 200; inspect the top-level `status` and `readiness.checks` fields. ## Runs API (streaming-friendly alternative) [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#runs-api-streaming-friendly-alternative "Direct link to Runs API (streaming-friendly alternative)") In addition to `/v1/chat/completions` and `/v1/responses`, the server exposes a **runs** API for long-form sessions where the client wants to subscribe to progress events instead of managing streaming themselves. ### POST /v1/runs [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#post-v1runs "Direct link to POST /v1/runs") Create a new agent run. Returns a `run_id` that can be used to subscribe to progress events. ```json { "run_id": "run_abc123", "status": "started" } ``` Runs accept a simple `input` string and optional `session_id`, `instructions`, `conversation_history`, or `previous_response_id`. When `session_id` is provided, Hermes surfaces it in the run status so external UIs can correlate runs with their own conversation IDs. ### GET /v1/runs/{run\_id} [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-v1runsrun_id "Direct link to GET /v1/runs/{run_id}") Poll the current run state. This is useful for dashboards that need status without holding an SSE connection open, or for UIs that reconnect after navigation. ```json { "object": "hermes.run", "run_id": "run_abc123", "status": "completed", "session_id": "space-session", "model": "hermes-agent", "output": "Done.", "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250} } ``` Statuses are retained briefly after terminal states (`completed`, `failed`, or `cancelled`) for polling and UI reconciliation. ### GET /v1/runs/{run\_id}/events [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-v1runsrun_idevents "Direct link to GET /v1/runs/{run_id}/events") Server-Sent Events stream of the run's tool-call progress, token deltas, and lifecycle events. Designed for dashboards and thick clients that want to attach/detach without losing state. Unconsumed event buffers expire after five minutes so a detached client cannot grow memory indefinitely. This expires transport state only: a run that is still executing remains visible to status polling, approval, stop control, and concurrency accounting until its executor work actually exits. A connected SSE subscriber continues draining normally. ### POST /v1/runs/{run\_id}/stop [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#post-v1runsrun_idstop "Direct link to POST /v1/runs/{run_id}/stop") Interrupt a running agent turn. The endpoint returns immediately with `{"status": "stopping"}` while Hermes asks the active agent to stop at the next safe interruption point. The run stays tracked as `stopping` until the executor-backed work exits, then settles as `cancelled`; requesting stop never hides a worker that is still running. ### POST /v1/runs/{run\_id}/approval [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#post-v1runsrun_idapproval "Direct link to POST /v1/runs/{run_id}/approval") Resolve a pending approval for a run that is waiting on a human decision (for example, a tool call gated behind an approval policy). The body carries the approval decision; the run resumes once the decision is recorded. This endpoint is advertised in `/v1/capabilities` as the `run_approval` feature so external UIs can detect support before surfacing an approval prompt. ## Jobs API (background scheduled work) [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#jobs-api-background-scheduled-work "Direct link to Jobs API (background scheduled work)") The server exposes a lightweight jobs CRUD surface for managing scheduled / background agent runs from a remote client. All endpoints are gated behind the same bearer auth. ### GET /api/jobs [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-apijobs "Direct link to GET /api/jobs") List all scheduled jobs. ### POST /api/jobs [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#post-apijobs "Direct link to POST /api/jobs") Create a new scheduled job. Body accepts the same shape as `hermes cron` — prompt, schedule, skills, provider override, delivery target. ### GET /api/jobs/{job\_id} [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#get-apijobsjob_id "Direct link to GET /api/jobs/{job_id}") Fetch a single job's definition and last-run state. ### PATCH /api/jobs/{job\_id} [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#patch-apijobsjob_id "Direct link to PATCH /api/jobs/{job_id}") Update fields on an existing job (prompt, schedule, etc.). Partial updates are merged. ### DELETE /api/jobs/{job\_id} [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#delete-apijobsjob_id "Direct link to DELETE /api/jobs/{job_id}") Remove a job. Also cancels any in-flight run. ### POST /api/jobs/{job\_id}/pause [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#post-apijobsjob_idpause "Direct link to POST /api/jobs/{job_id}/pause") Pause a job without deleting it. Next-scheduled-run timestamps are suspended until resumed. ### POST /api/jobs/{job\_id}/resume [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#post-apijobsjob_idresume "Direct link to POST /api/jobs/{job_id}/resume") Resume a previously paused job. ### POST /api/jobs/{job\_id}/run [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#post-apijobsjob_idrun "Direct link to POST /api/jobs/{job_id}/run") Trigger the job to run immediately, out of schedule. ## Sessions API (session control over REST) [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#sessions-api-session-control-over-rest "Direct link to Sessions API (session control over REST)") External UIs can manage Hermes sessions over REST without standing up the dashboard. All endpoints are gated by `API_SERVER_KEY` and live under `/api/sessions/*`. | Method | Path | Description | | --- | --- | --- | | `GET` | `/api/sessions` | List sessions (paginated — `limit`, `offset`, `source`, `include_children`) | | `POST` | `/api/sessions` | Create an empty session | | `GET` | `/api/sessions/{id}` | Read session metadata | | `PATCH` | `/api/sessions/{id}` | Update title or `end_reason` | | `DELETE` | `/api/sessions/{id}` | Delete a session | | `GET` | `/api/sessions/{id}/messages` | Message history for a session | | `POST` | `/api/sessions/{id}/fork` | Branch the session via `SessionDB` lineage (matches CLI `/branch` semantics) | | `POST` | `/api/sessions/{id}/chat` | Run one synchronous agent turn | | `POST` | `/api/sessions/{id}/chat/stream` | SSE wrapper over a single turn — emits `assistant.delta`, `tool.started`, `tool.completed`, `run.completed` events | `/v1/capabilities` advertises the full surface via `session_*` feature flags and `endpoints.session_*` entries so external UIs can detect support and fall back safely. Inline images are supported in `chat` and `chat/stream` payloads (multimodal-aware path). ```bash # fork a session and run one turn curl -X POST http://localhost:8642/api/sessions/$ID/fork \ -H "Authorization: Bearer $API_SERVER_KEY" \ -d '{"title": "explore alt path"}' # stream a turn over SSE curl -N -X POST http://localhost:8642/api/sessions/$ID/chat/stream \ -H "Authorization: Bearer $API_SERVER_KEY" \ -d '{"input": "what files changed in the last hour?"}' ``` ## Skills and toolsets discovery [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#skills-and-toolsets-discovery "Direct link to Skills and toolsets discovery") `GET /v1/skills` and `GET /v1/toolsets` let external clients enumerate the agent's capabilities deterministically over REST instead of asking the model. Both are read-only and gated by `API_SERVER_KEY`. ```bash curl http://localhost:8642/v1/skills \ -H "Authorization: Bearer $API_SERVER_KEY" # → [{"name": "github-pr-workflow", "description": "...", "category": "..."}, ...] curl http://localhost:8642/v1/toolsets \ -H "Authorization: Bearer $API_SERVER_KEY" # → [{"name": "core", "label": "...", "description": "...", "enabled": true,\ # "configured": true, "tools": ["read_file", "write_file", ...]}, ...] ``` `/v1/skills` returns the same metadata the skills hub uses internally. `/v1/toolsets` returns toolsets resolved for the `api_server` platform with the concrete `tools` list each one expands to. Both are advertised under `endpoints.*` in `/v1/capabilities`. ## Long-term memory scoping (`X-Hermes-Session-Key`) [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#long-term-memory-scoping-x-hermes-session-key "Direct link to long-term-memory-scoping-x-hermes-session-key") Multi-user frontends like Open WebUI need a stable per-channel identifier for long-term memory (Honcho, etc.) that is **independent** of the transcript-scoped `X-Hermes-Session-Id` (which rotates on `/new`). Pass `X-Hermes-Session-Key` on `/v1/chat/completions`, `/v1/responses`, or `/v1/runs` and Hermes threads it through to `AIAgent(gateway_session_key=...)`, where the Honcho memory provider uses it to derive a stable scope. ```http POST /v1/chat/completions HTTP/1.1 Authorization: Bearer *** X-Hermes-Session-Id: transcript-alpha X-Hermes-Session-Key: agent:main:webui:dm:user-42 ``` Rules: max 256 chars, control characters (`\r`, `\n`, `\x00`) are rejected, and the value is echoed back on responses (JSON + SSE). `/v1/capabilities` advertises support via `"session_key_header": "X-Hermes-Session-Key"`. Without the key, Honcho's `per-session` strategy produces a different scope per `session_id` — exactly the behavior Hermes had before. ## System Prompt Handling [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#system-prompt-handling "Direct link to System Prompt Handling") When a frontend sends a `system` message (Chat Completions) or `instructions` field (Responses API), hermes-agent **layers it on top** of its core system prompt. Your agent keeps all its tools, memory, and skills — the frontend's system prompt adds extra instructions. This means you can customize behavior per-frontend without losing capabilities: - Open WebUI system prompt: "You are a Python expert. Always include type hints." - The agent still has terminal, file tools, web search, memory, etc. ## Authentication [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#authentication "Direct link to Authentication") Bearer token auth via the `Authorization` header: ```text Authorization: Bearer *** ``` Configure the key via `API_SERVER_KEY` env var. If you need a browser to call Hermes directly, also set `API_SERVER_CORS_ORIGINS` to an explicit allowlist. Security The API server gives full access to hermes-agent's toolset, **including terminal commands**. `API_SERVER_KEY` is **required for every deployment**, including the default loopback bind on `127.0.0.1`. Keep `API_SERVER_CORS_ORIGINS` narrow to control browser access when you explicitly allow browser callers. ## Configuration [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#configuration "Direct link to Configuration") ### Environment Variables [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#environment-variables "Direct link to Environment Variables") | Variable | Default | Description | | --- | --- | --- | | `API_SERVER_ENABLED` | `false` | Enable the API server | | `API_SERVER_PORT` | `8642` | HTTP server port | | `API_SERVER_HOST` | `127.0.0.1` | Bind address (localhost only by default) | | `API_SERVER_KEY` | _(required)_ | Bearer token for auth | | `API_SERVER_CORS_ORIGINS` | _(none)_ | Comma-separated allowed browser origins | | `API_SERVER_MODEL_NAME` | _(profile name)_ | Model name on `/v1/models`. Defaults to profile name, or `hermes-agent` for default profile. | ### config.yaml [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#configyaml "Direct link to config.yaml") ```yaml # Not yet supported — use environment variables. # config.yaml support coming in a future release. ``` ## Security Headers [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#security-headers "Direct link to Security Headers") All responses include security headers: - `X-Content-Type-Options: nosniff` — prevents MIME type sniffing - `Referrer-Policy: no-referrer` — prevents referrer leakage ## CORS [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#cors "Direct link to CORS") The API server does **not** enable browser CORS by default. For direct browser access, set an explicit allowlist: ```bash API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000 ``` When CORS is enabled: - **Preflight responses** include `Access-Control-Max-Age: 600` (10 minute cache) - **SSE streaming responses** include CORS headers so browser EventSource clients work correctly - **`Idempotency-Key`** is an allowed request header — clients can send it for deduplication (responses are cached by key for 5 minutes) Most documented frontends such as Open WebUI connect server-to-server and do not need CORS at all. ## Compatible Frontends [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#compatible-frontends "Direct link to Compatible Frontends") Any frontend that supports the OpenAI API format works. Tested/documented integrations: | Frontend | Stars | Connection | | --- | --- | --- | | [Open WebUI](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui) | 126k | Full guide available | | LobeChat | 73k | Custom provider endpoint | | LibreChat | 34k | Custom endpoint in librechat.yaml | | AnythingLLM | 56k | Generic OpenAI provider | | NextChat | 87k | BASE\_URL env var | | ChatBox | 39k | API Host setting | | Jan | 26k | Remote model config | | HF Chat-UI | 8k | OPENAI\_BASE\_URL | | big-AGI | 7k | Custom endpoint | | OpenAI Python SDK | — | `OpenAI(base_url="http://localhost:8642/v1")` | | curl | — | Direct HTTP requests | ## Multi-User Setup with Profiles [​](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server\#multi-user-setup-with-profiles "Direct link to Multi-User Setup with Profiles") To give multiple users their own isolated Hermes instance (separate config, memory, skills), use [profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles): ```bash # Create a profile per user hermes profile create alice hermes profile create bob # Configure each profile's API server on a different port. API_SERVER_* are env # vars (not config.yaml keys), so write them to each profile's .env: cat >> ~/.hermes/profiles/alice/.env <> ~/.hermes/profiles/bob/.env <