Diagnostics & accounts

No auth

The one unauthenticated route — a cheap liveness check. Not wrapped in the data envelope.

{ "status": "ok", "app": "SocialMate", "version": "2.0.0", "timestamp": "…", "uptimeSec": 3601 }

scope: read

Build identity — handy when filing an issue.

curl http://localhost:3456/v1/version \
  -H "x-api-key: YOUR_KEY"

{ "data": { "app": "SocialMate", "version": "2.0.0", "electron": "…", "node": "…", "gitCommit": "…" } }

scope: read

A deep health snapshot: DB connectivity, tunnel URL, per-account connection state, queue counters, and how many webhook endpoints are auto-disabled.

curl http://localhost:3456/v1/status \
  -H "x-api-key: YOUR_KEY"

{
  "data": {
    "ok": true,
    "database": { "ok": true },
    "tunnel": { "url": "https://your-name.trycloudflare.com" },
    "adapters": [ { "accountId": "a1b2c3", "state": "connected" } ],
    "queue": { "pending": 4, "processing": 1, "failed": 0 },
    "webhooks": { "brokenEndpoints": 0 },
    "timestamp": "…"
  }
}

scope: readFree

The integration handshake — the first call any integration should make (it powers the n8n node's "Test connection"). One round-trip returns the license tier (so you can grey out Pro-only operations instead of surfacing a raw 402), the enabled feature flags, the tunnel mode/URL, the key's account scope, and the account list.

curl http://localhost:3456/v1/capabilities \
  -H "x-api-key: YOUR_KEY"

{
  "data": {
    "app": "SocialMate", "version": "2.0.0", "tier": "pro",
    "features": { "apiWriteEnabled": true, "localMessageCache": true, "scheduledMessages": true },
    "tunnel": { "mode": "named", "url": "https://api.example.com" },
    "keyScope": null,
    "accounts": [ { "id": "a1b2c3", "phone": "15551234567", "name": "Sales", "status": "connected" } ]
  }
}

scope: readFree

A lighter probe than /v1/status when you only need the public address and port — e.g. to print the current quick-tunnel URL (which rotates) in a setup script.

{ "data": { "tunnelUrl": "https://your-name.trycloudflare.com", "apiPort": 3456, "app": "SocialMate", "version": "2.0.0" } }

scope: read

Every linked account with its live risk and warming snapshot.

{
  "data": [
    {
      "id": "a1b2c3", "phone": "15551234567", "name": "Sales line", "status": "connected",
      "riskLevel": "safe", "riskScore": 23, "warmingDay": 1, "messagesToday": 41, "dailyLimit": 500
    }
  ]
}

scope: read

One account's detail. 404 if the id is unknown.

curl http://localhost:3456/v1/accounts/ACCOUNT_ID \
  -H "x-api-key: YOUR_KEY"

{ "data": { "id": "a1b2c3", "phone": "15551234567", "name": "Sales", "status": "connected", "dailyLimit": 500, "state": "connected" } }

scope: read

All chats for the account (individual and group). No query params. Group-only? See Groups.

curl http://localhost:3456/v1/accounts/ACCOUNT_ID/chats \
  -H "x-api-key: YOUR_KEY"

{ "data": [ { "id": "[email protected]", "name": "Acme", "type": "individual", "lastMessagePreview": "See you then!", "lastMessageAt": 1718800000000, "unreadCount": 0 } ] }

scope: read

Bounded, searchable contact list. Query params: search, limit (max 500, default 100), offset. Always returns the paginated envelope ({ data, pagination }). Pass limit/offset to page; omit them to get the full list in one page (pagination.total still reports the count).

curl "http://localhost:3456/v1/accounts/ACCOUNT_ID/contacts?search=jane&limit=50" \
  -H "x-api-key: YOUR_KEY"

{ "data": [ { "id": "155512300001", "name": "Jane", "phone": "155512300001" } ], "pagination": { "limit": 50, "offset": 0, "total": 1 } }

scope: read

A single contact. 404 if not found on this account.

curl http://localhost:3456/v1/accounts/ACCOUNT_ID/contacts/155512300001 \
  -H "x-api-key: YOUR_KEY"

{ "data": { "id": "155512300001", "name": "Jane", "phone": "155512300001", "jid": "[email protected]" } }

scope: send Pro · agentMemory

Agent Memory. Save what your AI agent learned about a contact — a customName, notes, email, company or tags. The custom name then shows in the Live feed, message history and GET /ai-context, and a WhatsApp sync can never overwrite it. Create-if-missing: a contactId the WhatsApp contact list never carried (a plain phone number in international format, or a senderId from a webhook) is created. A provided field is saved, null clears it, an omitted field is left unchanged; a group id returns 400. SocialMate stores what your agent learned — it never generates it.

curl -X PATCH http://localhost:3456/v1/accounts/ACCOUNT_ID/contacts/155512300001 \
  -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "customName": "Jane (VIP)", "company": "Acme", "tags": ["vip","lead"] }'

{ "data": { "success": true, "created": false,
  "contact": { "id": "155512300001", "displayName": "Jane (VIP) . 155512300001",
    "customName": "Jane (VIP)", "company": "Acme", "tags": ["vip","lead"] } } }