TAK Gateway

Cursor on Target ingestion and real-time streaming for the Socialmesh mesh radio platform. Accepts CoT XML over UDP and HTTP, normalizes events to JSON, and streams to authenticated clients via WebSocket.

Operational v1.0.0 UDP Listening
0
Events Accepted
0
Active Entities
0
WS Clients
9d 23h 15m
Uptime

Endpoints

GET /health

Health check endpoint. Returns service status and timestamp. Unauthenticated — used by Railway and the API Gateway for liveness probes.

Example Request

curl https://tak.socialmesh.app/health

Response 200 OK

{ "status": "ok", "service": "tak-gateway", "timestamp": "2026-03-15T08:00:00.000Z", "uptimeMs": 3600000 }

GET /ready

Readiness check. Verifies that the server is initialized, Firebase auth is configured (if enabled), and the protobuf decoder is reachable (if enabled). Returns 503 with reasons if not ready.

Example Request

curl https://tak.socialmesh.app/ready

Response 200 OK

{ "ready": true, "service": "tak-gateway" }

GET /v1/tak/status

Detailed gateway status including UDP listener state, event counters, connected clients, decoder health, and build info. Requires Firebase authentication.

Example Request

curl -H "Authorization: Bearer <firebase-token>" \ https://tak.socialmesh.app/v1/tak/status

Response 200 OK

{ "udpListening": true, "udpPort": 4242, "totalEventsReceived": 1542, "totalEventsDeduplicated": 38, "activeKeys": 12, "connectedClients": 3, "uptimeMs": 3600000 }

GET /v1/tak/events

Backfill endpoint. Returns recent CoT events, optionally filtered by timestamp. Without sinceUtcMs, returns the latest snapshot of all active entities. Requires Firebase authentication.

Query Parameters

ParamTypeDefaultDescription
sinceUtcMs integer — Return events received after this UTC timestamp (ms). Omit for latest snapshot.
limit integer 500 Maximum events to return (max 1000)

Example Request

curl -H "Authorization: Bearer <firebase-token>" \ "https://tak.socialmesh.app/v1/tak/events?sinceUtcMs=1710489600000&limit=100"

Response 200 OK

{ "events": [ { "uid": "ATAK-12345", "type": "a-f-G-U-C", "callsign": "Alpha-1", "lat": 34.0522, "lon": -118.2437, "timeUtcMs": 1710489600000, "staleUtcMs": 1710489900000, "receivedUtcMs": 1710489601234 } ], "count": 1 }

POST /v1/tak/inject

HTTP ingestion endpoint. Push CoT events via raw XML (application/xml) or pre-normalized JSON (application/json). Requires Firebase authentication.

XML Example

curl -X POST \ -H "Authorization: Bearer <firebase-token>" \ -H "Content-Type: application/xml" \ -d '<event uid="ATAK-12345" type="a-f-G-U-C" time="..." start="..." stale="..."> <point lat="34.0522" lon="-118.2437" hae="100" ce="10" le="10"/> </event>' \ https://tak.socialmesh.app/v1/tak/inject

JSON Example

curl -X POST \ -H "Authorization: Bearer <firebase-token>" \ -H "Content-Type: application/json" \ -d '{"uid":"ATAK-12345","type":"a-f-G-U-C","lat":34.0522,"lon":-118.2437}' \ https://tak.socialmesh.app/v1/tak/inject

Response 200 OK

{ "accepted": true, "event": { "uid": "ATAK-12345", "type": "a-f-G-U-C", "lat": 34.0522, "lon": -118.2437, // ... normalized fields } }

WS /v1/tak/stream

Real-time WebSocket stream. Receives normalized CoT events as they are ingested. Supports scope filtering via query parameter. Requires Firebase authentication via token query parameter.

Query Parameters

ParamTypeDefaultDescription
token string — Firebase ID token for authentication required
scope string — Optional scope filter for event types

Connection Example

// JavaScript const ws = new WebSocket( "wss://tak.socialmesh.app/v1/tak/stream?token=<firebase-token>" ); ws.onmessage = (msg) => { const event = JSON.parse(msg.data); console.log(event.uid, event.callsign, event.lat, event.lon); };

Ingestion

UDP Ingestion

The gateway listens for CoT XML on UDP port 4242 (unicast). Multicast ingestion on 239.2.3.1:6969 can be enabled via environment variable. Both plain-text XML and TAK Protocol v1 framed payloads are supported. Protobuf payloads are forwarded to the tak-decoder sidecar when enabled.

Error Responses

Standard Error Format

{ "error": "Description of what went wrong" }
CodeMeaning
400Invalid CoT XML or missing required fields
401Missing or invalid Firebase authentication token
413Payload too large (max 64KB)
429Rate limit exceeded (300 requests/minute per IP)
500Internal server error
503Service not ready (readiness check failed)

Authentication

All /v1/ endpoints and the WebSocket stream require a valid Firebase ID token. Pass it as a Bearer token in the Authorization header for REST requests, or as a token query parameter for WebSocket connections. An optional UID allowlist can restrict access to specific Firebase users.

CORS

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

About TAK

Cursor on Target (CoT) is an XML-based protocol used by ATAK, WinTAK, and iTAK for sharing situational awareness data. The TAK Gateway bridges CoT data sources with the Socialmesh app, enabling mesh radio operators to see TAK entities on the map alongside Meshtastic nodes.

Events ingested via UDP or HTTP are deduplicated, normalized to JSON, stored in a sliding time window, and streamed to connected WebSocket clients in real time.