Gateway API
HTTP and WebSocket routes exposed by the Artemis gateway server.
The gateway is the single entry point for everything—the Web UI, CLI, Discord bot, WhatsApp integration, and any external client all talk to it. It's a Fastify server that boots on port 4081 by default.
When the gateway starts, it initialises AgentCore, registers all MCP servers, loads the tool registry, and opens the WebSocket listeners. Everything else is just routes on top of that.
WebSocket — Chat
This is where the streaming chat happens. Send a JSON payload and get back a stream of events.
Client → Server payload:
{
"content": "string",
"userId": "string",
"channelId": "web | discord | whatsapp | telegram | cli",
"sessionId": "string (optional)",
"provider": "string (optional)",
"model": "string (optional)",
"images": ["base64... (optional)"]
}Server → Client event stream:
Each message is a JSON object with a type field:
| Type | Payload fields | Description |
|---|---|---|
token | text | Streamed output token |
reasoning | text | Chain-of-thought text |
monologue | text | Internal reflection (not shown to user) |
tool_call | id, name, arguments | Model invoked a tool |
tool_result | id, result | Tool execution result |
browser_status | text | Browser agent status update |
context_info | text | Contextual metadata |
paused | — | Agent waiting (e.g. for tool confirmation) |
done | sessionId, usage | Stream complete |
error | message | Error during generation |
WebSocket — Admin
A secondary WebSocket channel for the CLI's OTP dashboard. The gateway pushes incoming authorization requests here so the artemis otp TUI can display and action them in real time.
REST Routes
Health
Returns { status: "ok" }. Use this to check if the gateway is reachable.
Models
Aggregates available models from all configured providers. Ollama and LM Studio are queried dynamically at request time; all other providers return a static list based on what's enabled in your config.
Vertex AI models are always included in the response regardless of which authentication method you have configured.
History
Session history read and write. The gateway delegates to MemoryManager which uses a SQLite backend with optional Redis caching.
Brain
Returns a full snapshot of the agent's internal state graph—providers, file memory contents, native tools, in-process MCP servers, and channel connection statuses. The Web UI's 3D brain-map visualization reads from this endpoint.
Memories
Read and write the ~/.artemis/workspace/ markdown files (SOUL.MD, OWNER.MD, MEMORY.MD, TOOLS.MD) directly. Used by the artemis brain TUI and the Web UI memory editor.
Files
File upload for attachment support. Accepts multipart form data and returns an Attachment object that can be included in subsequent chat messages.
Channels
Manage the Discord, WhatsApp, Telegram, and Gmail channel processes. The gateway spawns and monitors these as child processes with automatic restart logic. Use these routes to connect or disconnect channels without restarting the gateway.
Auth
OTP authorization management. New users requesting access show up here; admin approves via the artemis otp TUI, which in turn calls this endpoint.
Onboarding
Returns { firstRun: true } if no OWNER.MD exists yet. The Web UI uses this to decide whether to show the onboarding wizard on first visit.
Bridge
Cloudflare Worker bridge management for remote access. Lets you expose the gateway securely without opening ports.
Network Binding
By default the gateway binds to 127.0.0.1 (localhost only). Set BASE_IP=0.0.0.0 to expose it on all network interfaces—useful when running the gateway on a home server or in a container and connecting from other devices.
BASE_IP=0.0.0.0BASE_IP is respected by the gateway, the WhatsApp internal API, and the Discord/Telegram/Gmail subprocesses, so all services follow the same binding policy from a single env var.