API
Protected REST and MCP calls require an Authorization bearer header by default. In that mode, each WebSocket expects the operator token as its first text frame. With MODEMBOX_DISABLE_AUTH=true, omit the header and the first token frame. Tokenless endpoints reject a browser’s cross-origin requests. All clients share one instance.
| Method and path | Payload or result |
|---|---|
| GET /healthz | Public application liveness |
| GET /auth-mode | Public token requirement as {"tokenRequired": true} or {"tokenRequired": false} |
| GET /v1/state | Snapshot of devices, recent messages, activity, and hooks |
| GET /v1/modems | Device details, capabilities, SIM and network state, call state |
| GET /v1/messages | Use modem, before and limit query parameters. Returns items and next cursor |
| GET /v1/messages/{id} | One message, including segment status for multipart sends |
| POST /v1/modems/{id}/sms | number and text |
| POST /v1/modems/{id}/pin | pin and optional remember |
| DELETE /v1/modems/{id}/pin | Forget the saved PIN for the current SIM |
| POST /v1/modems/{id}/calls | number |
| POST /v1/modems/{id}/calls/answer | Empty JSON object |
| DELETE /v1/modems/{id}/calls/current | Hang up |
| GET /v1/modems/{id}/audio | Recent caller audio as base64 WAV. Optional seconds from 1 to 10 |
| POST /v1/modems/{id}/audio | wav, a base64 mono 8 kHz PCM16 WAV up to 30 seconds |
| DELETE /v1/modems/{id}/audio | Stop WAV playback |
| POST /v1/modems/{id}/at | command, a single allowed AT command |
| POST /mcp | MCP Streamable HTTP |
| GET /v1/hooks/{resource} | List rules, destinations, runs, or calls with limit and offset. Returns items, limit, offset, and hasMore |
| POST /v1/hooks/rules | Create a rule with name, trigger, modem, match, conditions and actions |
| PUT /v1/hooks/rules/{id} | Replace a rule, including its enabled state |
| POST /v1/hooks/destinations | Create an HTTP destination |
| PUT /v1/hooks/destinations/{id} | Replace an HTTP destination |
| DELETE /v1/hooks/{resource}/{id} | Delete a rule or destination and cancel queued actions |
| POST /v1/hooks/preview | Preview a draft rule against one messageId or callId |
See MCP and agent integrations for the tool list. Read-only AT commands are allowlisted. Raw writes require an operator opt-in and are unavailable during a call.
Use the ID returned by GET /v1/modems for modem actions and SMS filtering. Auto-discovered modems with a usable IMEI use a hardware UUID. Older messages retain their original modem ID in unfiltered message history. See device identity.
REST failures return a stable code and message.
SMS submission status
submitted means the modem accepted the SMS for sending. Carrier delivery is separate. A partial result means the modem accepted some segments before it rejected a later one. An unknown result means the send may have completed before transport loss. Check the parts array from GET /v1/messages/{id} for a multipart message before retrying.
WebSockets
/v1/events sends a snapshot with modems, messages and activity before sending modem, message and activity events. Sequence numbers increase in one running service. Reconnect for a fresh snapshot. Slow clients can receive a replacement snapshot.
A message event can include replaces, the IDs of old fragment rows to remove from the inbox when a multipart SMS is joined.
The snapshot includes hooks with rules, destinations, runs, and calls. Live events of type hook.rules, hook.destinations, hook.runs, and hook.calls replace the row with the same ID. Rule and destination deletions carry deleted: true. See the hooks guide for event payloads and delivery behavior.
/v1/modems/{id}/audio/ws sends binary 20 ms PCM frames during a call. Listening clients get caller audio. One browser at a time can request the microphone with mic:on and release it with mic:off. Send PCM16 mono 8 kHz in 320-byte frames. WAV playback takes precedence over queued microphone frames. Caller audio stays in a short in-memory buffer for capture.