This document describes the HTTP API provided by the Enhanced Mesh Dash server. The API allows you to retrieve current network status, historical data, and interact with the Meshtastic network by sending messages or triggering actions.
Endpoints generally return data in JSON format unless otherwise specified.
GET /sseEstablishes a Server-Sent Events (SSE) connection. Once connected, the server will push real-time updates to the client.
Events Sent:
connection_status: Updates on connection state (e.g., "Connected", "Disconnected").local_node_info: Information about the node directly connected to the server.nodes: Initial full list of known nodes upon connection.node_update: Sent when information about a specific node changes.packet: Sent whenever a new packet is received or processed.stats: Periodic updates of session statistics.error: Sent when a server-side error occurs related to Meshtastic.Clients should listen for these events on the established SSE connection.
These endpoints provide information about the current state of the network and server as known by the application.
GET /api/statusRetrieves the current connection status, local node info, last error, and server time.
Response Example: {"connection_status": "Connected", "local_node_info": {...}, "last_error": null, "server_time_unix": 1714006345.123}
GET /api/statsRetrieves current session statistics (packet counts, nodes seen, uptime etc.).
Response: JSON object containing various session counters.
GET /api/nodesRetrieves a dictionary of all currently known nodes, keyed by their Node ID (e.g., !aabbccdd).
Response: JSON object where keys are Node IDs and values are node data objects.
{/* Removed reference to backend model name */}GET /api/nodes/{node_id}Retrieves the current state of a specific node by its ID.
Path Parameter: {node_id} (string, e.g., !aabbccdd)
Response: JSON object representing the specific node's data or a 404 error if not found.
GET /api/packetsRetrieves the most recent packets stored in the server's memory cache.
Query Parameter: limit (integer, default 50, max depends on server config). Specifies the maximum number of packets to return.
Response: JSON array of recent packet objects.
These endpoints retrieve historical data stored in the server's database.
GET /api/packets/historyRetrieves historical packets from the database, ordered from most recent.
Query Parameter: limit (integer, default 100, max 10000). Specifies the maximum number of historical packets to return.
Response: JSON array of historical packet objects.
GET /api/messages/historyRetrieves historical text messages from the database, ordered from most recent.
Query Parameters:
limit (integer, default 100, max 5000): Max number of messages.from_id (string, optional): Filter by sender node ID (e.g., !aabbccdd).to_id (string, optional): Filter by recipient node ID (e.g., !aabbccdd or ^all for broadcast).channel (integer, optional): Filter by channel index.start_time (float, optional): Unix timestamp; only messages after this time.end_time (float, optional): Unix timestamp; only messages before this time.Response: JSON array of historical message objects.
GET /api/nodes/{node_id}/history/{history_type}Retrieves position or telemetry history for a specific node from the database.
Path Parameters:
{node_id} (string): The ID of the node (e.g., !aabbccdd).{history_type} (string): Must be either positions or telemetry.Query Parameters:
limit (integer, default 1000, max 10000): Max number of records.start_time (float, optional): Unix timestamp; only records after this time.end_time (float, optional): Unix timestamp; only records before this time.Response: JSON array of position or telemetry history objects, depending on {history_type}.
GET /api/nodes/{node_id}/count/{item_type}Retrieves the total count of specific item types associated with a node from the database history.
Path Parameters:
{node_id} (string): The ID of the node (e.g., !aabbccdd).{item_type} (string): Must be messages_sent, positions, or telemetry.Query Parameters:
start_time (float, optional): Unix timestamp; only count items after this time.end_time (float, optional): Unix timestamp; only count items before this time.Response Example: {"node_id": "...", "item_type": "...", "count": 123, ...}
GET /api/counts/totalsRetrieves the total historical counts for messages sent, positions recorded, and telemetry records across *all* nodes stored in the database.
Response Example: {"total_messages": 500, "total_positions": 1200, "total_telemetry": 800}
GET /api/metrics/averagesRetrieves the most recent calculated average mesh metrics (SNR/RSSI across non-local nodes) and a history of these averages.
Query Parameter: limit (integer, default 100, max 5000). Specifies the maximum number of historical average records to return.
Response: JSON object containing most_recent (single average metric object or null) and history (array of historical average metric objects).
These endpoints allow performing actions on the Meshtastic network.
POST /api/messagesSends a text message via the connected Meshtastic device. The request body must be JSON.
Request Body (JSON):
message (string, required): The text message to send.destination (string, optional): Target node ID (e.g., !aabbccdd) or ^all for broadcast. Defaults to broadcast (^all) if omitted.channel (integer, optional): Channel index to send on (default: 0).Response: 202 Accepted with JSON {"status": "queued", "detail": "..."} on success, or an error status code (e.g., 503 if not connected).
POST /api/hookA specific endpoint designed for simple external triggers (like IFTTT, Home Assistant webhooks) to send a message to a specific node. The request body must be JSON.
Request Body (JSON):
node_id (string, required): The target node ID. Must start with ! (e.g., !aabbccdd).message (string, required): The text message to send.channel (integer, optional): Channel index to send on (default: 0).Response: 202 Accepted with JSON {"status": "queued", "detail": "..."} on success, or an error status code.
POST /monitor/websiteMonitors a specific block of text content on a website and sends it as a message via Meshtastic. Useful for sending alerts based on website changes. The request body must be JSON.
Request Body (JSON):
url (string, required): The URL of the website to fetch.block_id (integer, required): The index of the text block to extract (obtained from the /extract endpoint).prefix (string, required): Text to prepend to the extracted content before sending.node_id (string, optional): Target node ID (e.g., !aabbccdd). Defaults to broadcast (^all) if omitted.channel (integer, optional): Channel index to send on (default: 0).Response: JSON object indicating success or failure, including the message sent and the text extracted.
Endpoints for fetching and parsing content from web pages.
POST /extractFetches content from a given URL, parses the HTML, and extracts identifiable text blocks. Useful for identifying content for the /monitor/website endpoint. The request body must be JSON.
Request Body (JSON):
url (string, required): The URL to fetch and parse.block_id (integer, optional): If provided, returns only the text block at this specific index.text_only (boolean, optional): If block_id is provided and this is true, returns only the plain text of that block (Content-Type: text/plain).Response (All Blocks): JSON object with url, total_blocks, and an array blocks containing objects with element_type, element_id, element_class, and text.
Response (Specific Block): JSON object with url, block_id, and the specific block object, OR plain text if text_only was true.
This API section allows for scheduling tasks (like sending messages or requesting sensor data) to be executed automatically based on a cron schedule.
All task-related endpoints are prefixed with /api/tasks.
Note: The specific endpoints below are inferred based on common REST practices and the likely structure of tasks_api.py. Verify against the actual implementation if needed.
GET /api/tasks/Retrieves a list of all currently scheduled tasks.
Response: JSON array of task objects.
POST /api/tasks/Creates a new scheduled task. The request body must be JSON.
Request Body (JSON):
nodeId (string, required): Target node ID (e.g., !aabbccdd).taskType (string, required): Type of task (e.g., message, sensor).actionPayload (string, required): The message text or sensor ID, depending on taskType.cronString (string, required): The schedule in standard 5-part cron format (e.g., 0 9 * * 1 for 9 AM every Monday).Response: JSON object of the created task.
GET /api/tasks/{task_id}Retrieves details for a specific scheduled task by its ID.
Path Parameter: {task_id} (integer)
Response: JSON object of the specific task or 404 error.
PUT /api/tasks/{task_id}Updates an existing scheduled task. Request body is the same as for POST.
Path Parameter: {task_id} (integer)
Response: JSON object of the updated task or 404 error.
DELETE /api/tasks/{task_id}Deletes a specific scheduled task by its ID.
Path Parameter: {task_id} (integer)
Response: Success message (e.g., {"message": "Task deleted"}) or 404 error.
GET /api/tasks/sensors/{node_id}Retrieves a list of available sensors reported by a specific node (if the node supports the Sensor module and has reported them). Used by the Task Scheduler UI.
Path Parameter: {node_id} (string)
Response Example: JSON array like [{"id": "BATT", "name": "Battery"}, {"id": "...", "name": "..."}] or 404/empty array if none found.
The server also provides several HTML pages for user interaction:
GET /: Main DashboardGET /network: Network VisualizationGET /map: Map VisualizationGET /sensors: Sensor Data PageGET /hook: Webhook Information PageGET /tasks: Task Scheduler InterfaceGET /api_documentation.html: This API Documentation page