Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chamilonster/Piumy/llms.txt

Use this file to discover all available pages before exploring further.

Piumy serves a REST API on port 8080 (controlled by PIMYWA_API_ADDR) from the same binary as the MCP server. It’s designed for quick access from curl, shell scripts, or the dashboard — no MCP client setup needed. Both the MCP server and REST API share the same store and in-memory state, so every read reflects the current live switchboard.

​
Authentication

If PIMYWA_API_KEY is set, every /api/* request must include it via the X-API-Key header or the ?key= query parameter: 
# Via header (preferred — keeps the key out of proxy logs)
curl http://piumy.local:8080/api/status -H "X-API-Key: <key>"

# Via query param (convenient for EventSource / browser SSE)
curl "http://piumy.local:8080/api/status?key=<key>"
The auth check is enforced on every /api/* path. The /healthz endpoint is always unauthenticated.
An empty PIMYWA_API_KEY leaves the API completely open. This is acceptable for local development but never for a production deployment. At minimum, bind PIMYWA_API_ADDR to a loopback or private LAN interface rather than 0.0.0.0 when running without a key.

​
Base URL

http://<host>:8080
Replace <host> with your board’s hostname (e.g. piumy.local) or IP address. The port is configurable via PIMYWA_API_ADDR; :8080 is the default.

​
Endpoints summary

MethodPathDescription
GET/healthzHealth check — no auth required
GET/api/statusCurrent switchboard status snapshot
GET/api/chatsList recent chats
GET/api/messagesMessages from a specific chat
GET/api/queueAdvanced-mode messages waiting for an agent
POST/api/sendQueue a message to send
POST/api/modeSet a chat’s mode (auto / advanced)
POST/api/escalateEscalate a chat to advanced mode
POST/api/handledMark a message as handled
GET/api/battery/logDischarge/charge trace (historical CSV rows)
GET/api/eventsServer-sent events (SSE) stream
GET/api/qr.svgCurrent QR code as an SVG image
GET/api/settingsCurrent runtime settings
POST/api/settingsUpdate runtime settings
GET/api/killswitchKill switch (mute) state
POST/api/killswitchToggle the kill switch
GET/api/gatewayGateway running state and connection info
POST/api/gatewayStart or stop the WhatsApp gateway
POST/api/reconnectResume the gateway after a reconnect pause
GET/api/backupSession backup status
POST/api/backupTrigger a manual backup
GET/api/mcp-guardMCP anti-flood limiter status
POST/api/mcp-guardUpdate MCP anti-flood thresholds
GET/api/routerCurrent router config snapshot
POST/api/router/whitelistAdd or remove a JID from the whitelist
POST/api/router/allowallEnable or disable the allow-all flag
GET/api/rulesGlobal and by-type rules tiers
POST/api/rules/typeSet by-type rules (individual or group)
POST/api/rules/defaultSet the global default rules
POST/api/chats/bossMark or unmark a chat as the trusted owner
POST/api/chats/rulesSet per-chat behavior rules
POST/api/chats/descriptionSet a chat’s description
POST/api/chats/confirmationSet a chat’s confirmation mode
POST/api/drafts/approveApprove a pending auto-reply draft
POST/api/drafts/discardDiscard a pending auto-reply draft
For the full request/response shapes, parameter details, and curl examples for each endpoint, see REST API Endpoints.

Build docs developers (and LLMs) love

Get started for freeTalk to us