REST API Reference

All endpoints use HTTP authorization as a request parameter (not a header). The value is Base64-encoded useragent:access_key.

Responses include X-HiveMind-HTTP-Replica and X-HiveMind-HTTP-Session-Backend headers. With the default in-memory session backend, clients or reverse proxies should keep one HTTP session on the same replica. Redis-backed session state removes that requirement.

Authentication

authorization = base64("my-satellite:abc123apikey")

The useragent is the client's display name. The access_key is the API key provisioned by hivemind-core add-client.

Endpoints

POST /connect

Register a client session on the server.

Parameters:

• authorization (string, required): Base64-encoded useragent:access_key.

Responses:

• 200 OK: {"status": "Connected"}
• 200 OK with an error body: {"error": "Missing authorization"} — the handler writes the error without setting a status, so the code stays 200
• 403 Forbidden: {"error": "Invalid authorization"} when the access key is not known.
• 500 Internal Server Error: {"error": "Connection failed"}

---

POST /disconnect

Remove a client session from the server.

Parameters:

• authorization (string, required): Base64-encoded useragent:access_key.

Responses:

• 200 OK: {"status": "Disconnected"}
• 200 OK: {"error": "Already Disconnected"} when no session exists for that key.
• 200 OK with an error body: {"error": "Missing authorization"} — the handler writes the error without setting a status, so the code stays 200
• 500 Internal Server Error: {"error": "Disconnection failed"}

---

POST /send_message

Send a HiveMessage to the server.

Parameters:

• authorization (string, required): Base64-encoded useragent:access_key.
• message (string, required): Encoded HiveMessage payload.

Responses:

• 200 OK: {"status": "message sent"}
• 200 OK: {"error": "Client is not connected"} when /connect was not called first.
• 400 Bad Request: {"error": "Missing message"}
• 403 Forbidden: {"error": "Invalid authorization"}
• 500 Internal Server Error: {"error": "Message sending failed"}

---

GET /get_messages

Poll for pending text messages from the server.

Parameters:

• authorization (string, required): Base64-encoded useragent:access_key.

Responses:

• 200 OK: {"status": "messages retrieved", "messages": ["<encoded_message1>", "<encoded_message2>"]}
• 200 OK: {"error": "Client is not connected"} when /connect was not called first.
• 200 OK with an error body: {"error": "Missing authorization"} — the handler writes the error without setting a status, so the code stays 200
• 500 Internal Server Error: {"error": "Retrieving messages failed"}

The messages list may be empty if no messages are pending. Clients should poll at an appropriate interval (e.g. every 1–5 seconds).

---

GET /get_binary_messages

Poll for pending binary messages from the server (for example, TTS audio).

Parameters:

• authorization (string, required): Base64-encoded useragent:access_key.

Responses:

• 200 OK: {"status": "messages retrieved", "b64_messages": ["<base64_message1>", "<base64_message2>"]}
• 200 OK: {"error": "Client is not connected"} when /connect was not called first.
• 200 OK with an error body: {"error": "Missing authorization"} — the handler writes the error without setting a status, so the code stays 200
• 500 Internal Server Error: {"error": "Retrieving messages failed"}

Binary payloads (e.g. TTS WAV data) are Base64-encoded in the response.

Polling model

The HTTP transport is stateful on the server side: the server buffers outbound messages per client session until the client polls /get_messages or /get_binary_messages. Clients must /connect before sending or polling, and /disconnect when done. A call that skips /connect still answers 200, with {"error": "Client is not connected"} as the body, so a client must read the body and not only the status code.

For real-time voice assistant use cases the WebSocket transport is preferred. Use HTTP when persistent TCP connections are not available.

---

Home · Architecture →