mirror of
https://github.com/MarekWo/mc-webui.git
synced 2026-03-28 17:42:45 +01:00
e9e04fb22d
Added technotes/API-Diagnostic-Commands.md with: - Complete curl examples for all API endpoints - SSH + docker exec one-liners for easy testing - Organized by category (health, contacts, device, channels, messages, DM, settings, archives) - Example JSON responses for each endpoint - Useful one-liners with jq for advanced queries - Quick troubleshooting section with logs and health checks - Notes on ports, methods, and response times This serves as a quick reference for debugging and testing the mc-webui API.
584 lines
13 KiB
Markdown
584 lines
13 KiB
Markdown
# API Diagnostic Commands - Quick Reference
|
|
|
|
**Server**: `192.168.1.2`
|
|
**SSH**: `ssh mcwebui@192.168.1.2`
|
|
|
|
**NOTE:** Replace the above example with your own server and credentials.
|
|
|
|
This cheatsheet contains useful commands for diagnosing mc-webui and meshcore-bridge using API endpoints.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Health Checks](#health-checks)
|
|
2. [Contact Management](#contact-management)
|
|
3. [Device Information](#device-information)
|
|
4. [Channel Management](#channel-management)
|
|
5. [Messages](#messages)
|
|
6. [Direct Messages (DM)](#direct-messages-dm)
|
|
7. [Settings](#settings)
|
|
8. [Archives](#archives)
|
|
|
|
---
|
|
|
|
## Health Checks
|
|
|
|
### Check meshcore-bridge health
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://meshcore-bridge:5001/health | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"serial_port": "/dev/serial/by-id/usb-Espressif_Systems_heltec_wifi_lora_32_v4__16_MB_FLASH__2_MB_PSRAM__90706984A000-if00",
|
|
"advert_log": "/root/.config/meshcore/MarWoj.adverts.jsonl"
|
|
}
|
|
```
|
|
|
|
### Check mc-webui connection status
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/status | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"connected": true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Contact Management
|
|
|
|
### Get all contacts (CLI type only, names only)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"count": 19,
|
|
"contacts": [
|
|
"SP7UNR_tdeck",
|
|
"Kosu 🦜",
|
|
"Arek",
|
|
"daniel5120 🔫",
|
|
"Szczwany-lis🦊"
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get detailed contacts (all types with metadata + last_seen)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts/detailed | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"count": 263,
|
|
"limit": 350,
|
|
"contacts": [
|
|
{
|
|
"name": "TK Zalesie Test 🦜",
|
|
"public_key_prefix": "df2027d3f2ef",
|
|
"type_label": "REP",
|
|
"path_or_mode": "Flood",
|
|
"last_seen": 1735429453,
|
|
"raw_line": "TK Zalesie Test 🦜 REP df2027d3f2ef Flood"
|
|
},
|
|
{
|
|
"name": "KRA C",
|
|
"public_key_prefix": "d103df18e0ff",
|
|
"type_label": "REP",
|
|
"path_or_mode": "Flood",
|
|
"last_seen": 1716206073
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get pending contacts (awaiting manual approval)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://meshcore-bridge:5001/pending_contacts | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"pending": [
|
|
{
|
|
"name": "C3396B62",
|
|
"public_key": "c3396b628ba34b96138d962fda81e5e5450be14fa212793d55c71fba967a6262"
|
|
}
|
|
],
|
|
"raw_stdout": "MarWoj|* pending_contacts\nMarWoj|* \n C3396B62: c3396b628ba34b96138d962fda81e5e5450be14fa212793d55c71fba967a6262"
|
|
}
|
|
```
|
|
|
|
Or via mc-webui API:
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts/pending | jq"
|
|
```
|
|
|
|
### Delete a contact (POST request)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
|
|
http://192.168.1.2:5000/api/contacts/delete \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{\"selector\": \"df2027d3f2ef\"}' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Contact removed successfully"
|
|
}
|
|
```
|
|
|
|
### Approve pending contact (POST request)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
|
|
http://192.168.1.2:5000/api/contacts/pending/approve \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{\"public_key\": \"c3396b628ba34b96138d962fda81e5e5450be14fa212793d55c71fba967a6262\"}' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Contact approved successfully"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Device Information
|
|
|
|
### Get device info
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/device/info | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"info": {
|
|
"device_name": "MarWoj",
|
|
"public_key": "11009cebbd2744d33c94b980b8f2475241fd2ca6165bd623e5ef00ec6982be6a...",
|
|
"battery": "100%",
|
|
"voltage": "4.20V"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Get device settings (persistent)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/device/settings | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"settings": {
|
|
"manual_add_contacts": false
|
|
}
|
|
}
|
|
```
|
|
|
|
### Update device settings (POST request)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
|
|
http://192.168.1.2:5000/api/device/settings \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{\"manual_add_contacts\": true}' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "manual_add_contacts set to on",
|
|
"settings": {
|
|
"manual_add_contacts": true
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Channel Management
|
|
|
|
### List all channels
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/channels | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"channels": [
|
|
{
|
|
"index": 0,
|
|
"name": "Public",
|
|
"key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
},
|
|
{
|
|
"index": 1,
|
|
"name": "Malopolska",
|
|
"key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get channel QR code (JSON format)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/channels/1/qr?format=json' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"qr_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
|
|
"channel": {
|
|
"index": 1,
|
|
"name": "Malopolska",
|
|
"key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Create new channel (POST request)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
|
|
http://192.168.1.2:5000/api/channels \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{\"name\": \"TestChannel\"}' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Channel created successfully",
|
|
"channel": {
|
|
"index": 2,
|
|
"name": "TestChannel",
|
|
"key": "auto-generated-key-here"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Delete channel (DELETE request)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X DELETE \
|
|
http://192.168.1.2:5000/api/channels/2 | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Channel removed successfully"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Messages
|
|
|
|
### Get messages for current channel
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/messages | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"messages": [
|
|
{
|
|
"timestamp": 1735430000,
|
|
"sender": "Kosu 🦜",
|
|
"text": "Hello from mesh!",
|
|
"type": "CHAN",
|
|
"channel_idx": 1
|
|
}
|
|
],
|
|
"count": 1
|
|
}
|
|
```
|
|
|
|
### Get messages for specific channel
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/messages?channel_idx=1' | jq"
|
|
```
|
|
|
|
### Get archived messages for specific date
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/messages?archive_date=2025-12-28&channel_idx=1' | jq"
|
|
```
|
|
|
|
### Send message (POST request)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
|
|
http://192.168.1.2:5000/api/messages \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{\"text\": \"Test message\", \"channel_idx\": 1}' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Message sent successfully"
|
|
}
|
|
```
|
|
|
|
### Check for new messages (smart refresh)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/messages/updates?last_seen={\"0\":1735430000,\"1\":1735429000}' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"updates": {
|
|
"0": {
|
|
"has_new": false,
|
|
"unread_count": 0
|
|
},
|
|
"1": {
|
|
"has_new": true,
|
|
"unread_count": 3
|
|
}
|
|
},
|
|
"total_unread": 3
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Direct Messages (DM)
|
|
|
|
### List DM conversations
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/dm/conversations | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"conversations": [
|
|
{
|
|
"conversation_id": "kosu_🦜",
|
|
"display_name": "Kosu 🦜",
|
|
"last_message_time": 1735430000,
|
|
"unread_count": 2
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get DM messages for specific conversation
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/dm/messages?conversation_id=kosu_🦜&limit=50' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"messages": [
|
|
{
|
|
"timestamp": 1735430000,
|
|
"sender": "Kosu 🦜",
|
|
"recipient": "MarWoj",
|
|
"text": "Private message text",
|
|
"type": "PRIV",
|
|
"pubkey_prefix": "df2027"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Send DM (POST request)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
|
|
http://192.168.1.2:5000/api/dm/messages \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{\"recipient\": \"Kosu 🦜\", \"text\": \"Test DM\"}' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "DM sent successfully"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Settings
|
|
|
|
### Trigger sync (force message refresh)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST http://192.168.1.2:5000/api/sync | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Sync triggered successfully"
|
|
}
|
|
```
|
|
|
|
### Send advert (normal)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
|
|
http://192.168.1.2:5000/api/device/command \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{\"command\": \"advert\"}' | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Command executed successfully"
|
|
}
|
|
```
|
|
|
|
### Send flood advert (use sparingly!)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST \
|
|
http://192.168.1.2:5000/api/device/command \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{\"command\": \"floodadv\"}' | jq"
|
|
```
|
|
|
|
---
|
|
|
|
## Archives
|
|
|
|
### List available archives
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/archives | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"archives": [
|
|
{
|
|
"date": "2025-12-28",
|
|
"display_date": "28 December 2025",
|
|
"file_path": "/mnt/archive/meshcore/2025-12-28.msgs"
|
|
},
|
|
{
|
|
"date": "2025-12-27",
|
|
"display_date": "27 December 2025",
|
|
"file_path": "/mnt/archive/meshcore/2025-12-27.msgs"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Trigger manual archiving (POST request)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -X POST http://192.168.1.2:5000/api/archive/trigger | jq"
|
|
```
|
|
**Response**:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Archive created successfully"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Useful One-Liners
|
|
|
|
### Count contacts by type
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts/detailed | jq '.contacts | group_by(.type_label) | map({type: .[0].type_label, count: length})'"
|
|
```
|
|
**Response**:
|
|
```json
|
|
[
|
|
{"type": "CLI", "count": 17},
|
|
{"type": "REP", "count": 226},
|
|
{"type": "ROOM", "count": 20}
|
|
]
|
|
```
|
|
|
|
### Get only active contacts (last_seen < 1 hour)
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://192.168.1.2:5000/api/contacts/detailed | jq --arg now \"\$(date +%s)\" '.contacts | map(select(.last_seen and (\$now | tonumber) - .last_seen < 3600))'"
|
|
```
|
|
|
|
### Check total unread messages across all channels
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s 'http://192.168.1.2:5000/api/messages/updates?last_seen={}' | jq '.total_unread'"
|
|
```
|
|
|
|
### List pending contacts with full keys
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s http://meshcore-bridge:5001/pending_contacts | jq '.pending[] | {name, key: .public_key}'"
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Troubleshooting
|
|
|
|
### Check if bridge is responding
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker exec mc-webui curl -s -w '\nHTTP Status: %{http_code}\n' http://meshcore-bridge:5001/health"
|
|
```
|
|
|
|
### Check if mc-webui is responding
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "curl -s -w '\nHTTP Status: %{http_code}\n' http://192.168.1.2:5000/api/status"
|
|
```
|
|
|
|
### View recent bridge logs
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker logs --tail 50 meshcore-bridge"
|
|
```
|
|
|
|
### View recent mc-webui logs
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker logs --tail 50 mc-webui"
|
|
```
|
|
|
|
### Follow logs in real-time
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "docker logs -f mc-webui"
|
|
```
|
|
|
|
### Check .msgs file size
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "ls -lh ~/.config/meshcore/MarWoj.msgs"
|
|
```
|
|
|
|
### Check .adverts.jsonl file size
|
|
```bash
|
|
ssh mcwebui@192.168.1.2 "ls -lh ~/.config/meshcore/MarWoj.adverts.jsonl"
|
|
```
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- **Port 5001** (meshcore-bridge): Internal only, accessible via `docker exec mc-webui`
|
|
- **Port 5000** (mc-webui): Publicly accessible on server
|
|
- All POST/DELETE requests require `Content-Type: application/json` header
|
|
- Use `jq` for pretty JSON formatting
|
|
- For debugging, add `-v` flag to curl for verbose output
|
|
- Response times should be < 500ms for most endpoints
|
|
- Bridge health endpoint includes serial port and advert log paths
|
|
|
|
---
|
|
|
|
**Last updated**: 2025-12-29
|
|
**mc-webui version**: Contact Management MVP v2 with "Last Seen" feature
|