Sigil API

REST API for storing and retrieving mesh node identity card snapshots. Each sigil captures a node's personality, stats, and encounter history as a shareable link.

Operational v1.0.0
3
Endpoints
30
Rate Limit / min
16 KB
Max Payload
SQLite
Storage

Base URL

https://sigil.socialmesh.app

Endpoints

POST /api/sigil

Store a sigil card snapshot. Returns a short ID and shareable URL.

Request Body

FieldTypeStatusDescription
nodeNum integer required Unique node number (positive integer)
displayName string required Node display name (max 100 chars)
hexId string required Hex identifier (max 20 chars)
trait string optional Node trait: wanderer, beacon, ghost, sentinel, relay, unknown
encounterCount integer optional Total encounters (0 – 1,000,000)
messageCount integer optional Total messages exchanged (0 – 1,000,000)
coSeenCount integer optional Co-seen node count (0 – 100,000)
ageDays integer optional Days since first seen (0 – 100,000)
maxDistance number optional Max recorded distance in meters
bestSnr integer optional Best signal-to-noise ratio (-128 to 127)
role string optional Meshtastic device role
hardwareModel string optional Hardware model name
firmwareVersion string optional Firmware version string
firstSeen string optional ISO 8601 date of first encounter

Example Request

curl -X POST https://sigil.socialmesh.app/api/sigil \ -H "Content-Type: application/json" \ -d '{ "nodeNum": 1234567890, "displayName": "Base Station Alpha", "hexId": "!a1b2c3d4", "trait": "sentinel", "encounterCount": 847, "messageCount": 2341, "ageDays": 142, "hardwareModel": "TBEAM" }'

Response 201 Created

{ "id": "V1StGXR8_Z", "url": "https://socialmesh.app/sigil/V1StGXR8_Z" }

GET /api/sigil/:id

Retrieve a stored sigil snapshot by its short ID.

Path Parameters

ParamTypeDescription
id string The sigil short ID (alphanumeric, max 30 chars)

Example Request

curl https://sigil.socialmesh.app/api/sigil/V1StGXR8_Z

Response 200 OK

{ "id": "V1StGXR8_Z", "nodeNum": 1234567890, "displayName": "Base Station Alpha", "hexId": "!a1b2c3d4", "trait": "sentinel", "encounterCount": 847, "messageCount": 2341, "coSeenCount": 0, "ageDays": 142, "maxDistance": null, "bestSnr": null, "role": null, "hardwareModel": "TBEAM", "firmwareVersion": null, "firstSeen": null, "createdAt": "2026-02-12 03:45:12" }

GET /health

Health check endpoint. Returns service status and timestamp.

Response 200 OK

{ "status": "ok", "service": "sigil-api", "timestamp": "2026-02-12T03:45:12.000Z" }

Error Responses

Standard Error Format

{ "error": "Description of what went wrong" }
CodeMeaning
400Invalid request body or malformed sigil ID
404Sigil not found
429Rate limit exceeded (max 30 POSTs per minute per IP)
500Internal server error

Rate Limiting

POST requests are rate-limited to 30 requests per minute per IP address. GET requests are not rate-limited. When the limit is exceeded, the API returns 429 Too Many Requests.

CORS

Cross-origin requests are allowed from socialmesh.app and localhost origins. Supported methods: GET, POST, OPTIONS.

About Sigils

A sigil is a unique geometric identity generated for each mesh radio node in the Socialmesh app. It visualizes the node's personality and history through procedural geometry, color, and animation. Sigil cards can be shared as links that render the full animated identity card in a browser.

View a sigil card at socialmesh.app/sigil by appending the sigil ID to the URL, e.g. socialmesh.app/sigil/V1StGXR8_Z.