Hydra
API Reference

Administrative control endpoints for managing a Hydra Node.

Control Plane

Control plane endpoints manage the node's lifecycle, sources, and monitoring. All require authentication via x-node-secret header or HMAC signature.

Authentication

Option 1 — Raw secret:

curl http://localhost:4002/control/status \
  -H "x-node-secret: my-secret"

Option 2 — Query parameter:

curl "http://localhost:4002/control/status?secret=my-secret"

Option 3 — HMAC signature (used by backend proxy):

# HMAC-SHA256(SHA256(secret), payload)
curl http://localhost:4002/control/status \
  -H "x-control-hmac: <signature>" \
  -H "x-control-timestamp: <unix-timestamp>"

GET /control/status

Returns detailed node status including resource usage.

curl http://localhost:4002/control/status \
  -H "x-node-secret: my-secret"

Response: 200 OK

{
  "status": "running",
  "version": "0.1.0",
  "uptime": "4h32m15s",
  "startedAt": "2026-03-21T04:00:00Z",
  "sources": {
    "adsb": { "enabled": true, "status": "running", "lastPoll": "2026-03-21T08:29:00Z" },
    "ais": { "enabled": true, "status": "running", "lastPoll": "2026-03-21T08:30:00Z" },
    "oref": { "enabled": true, "status": "running", "lastPoll": "2026-03-21T08:29:57Z" }
  },
  "memory": {
    "allocMB": 45.2,
    "sysMB": 72.8
  },
  "goroutines": 34,
  "cpuPercent": 2.1,
  "networkTxBytes": 15234567,
  "networkRxBytes": 89012345
}
Field Type Description
status string Always "running"
version string Binary version
uptime string Go duration
startedAt string ISO 8601 start time
sources object Per-source status map
memory.allocMB number Go heap allocation (MB)
memory.sysMB number Total system memory obtained (MB)
goroutines number Active goroutine count
cpuPercent number CPU usage percentage
networkTxBytes number Total bytes transmitted
networkRxBytes number Total bytes received

POST /control/restart

Triggers a full node restart. The restart happens asynchronously.

curl -X POST http://localhost:4002/control/restart \
  -H "x-node-secret: my-secret"

Response: 200 OK

{
  "status": "restarting"
}

POST /control/restart-source/{name}

Restarts a specific data source without restarting the entire node.

Path Parameters:

Param Type Values
name string adsb, ais, usgs, oref, cyber, airspace, telegram, xtracker, polymarket, maritime 
curl -X POST http://localhost:4002/control/restart-source/adsb \
  -H "x-node-secret: my-secret"

Response: 200 OK

{
  "status": "restarted",
  "source": "adsb"
}

POST /control/source/{name}/enable

Enable a data source that was previously disabled.

curl -X POST http://localhost:4002/control/source/cyber/enable \
  -H "x-node-secret: my-secret"

Response: 200 OK

{
  "status": "enabled",
  "source": "cyber"
}

POST /control/source/{name}/disable

Disable a running data source.

curl -X POST http://localhost:4002/control/source/cyber/disable \
  -H "x-node-secret: my-secret"

Response: 200 OK

{
  "status": "disabled",
  "source": "cyber"
}

GET /control/logs

Returns the last 200 log entries, optionally filtered.

Query Parameters:

Param Type Description
level string Filter by log level (debug, info, warn, error)
source string Filter by source name (e.g., adsb, ais) 
curl "http://localhost:4002/control/logs?level=error&source=adsb" \
  -H "x-node-secret: my-secret"

Response: 200 OK

[
  {
    "timestamp": "2026-03-21T08:15:00Z",
    "level": "error",
    "source": "adsb",
    "message": "RapidAPI rate limit exceeded, backing off 60s"
  }
]

GET /control/logs/stream

WebSocket endpoint for real-time log streaming.

Authentication options:

  1. x-node-secret header or ?secret= query
  2. HMAC token: ?token=<HMAC-SHA256(SHA256(secret), "logs:"+ts)>&ts=<timestamp> (valid 5 minutes)
const ws = new WebSocket('ws://localhost:4002/control/logs/stream?secret=my-secret');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'log') {
    console.log(`[${msg.data.level}] ${msg.data.source}: ${msg.data.message}`);
  }
  if (msg.type === 'metrics') {
    console.log(`CPU: ${msg.data.cpuPercent}% | Memory: ${msg.data.memoryMB}MB`);
  }
};

Initial message:

{
  "type": "log_history",
  "data": {
    "logs": [ /* last 500 log entries */ ]
  }
}

Streaming messages:

{
  "type": "log",
  "data": {
    "timestamp": "2026-03-21T08:30:00Z",
    "level": "info",
    "source": "ais",
    "message": "Processed 42 vessel positions"
  }
}

Metrics (every 3 seconds):

{
  "type": "metrics",
  "data": {
    "cpuPercent": 2.1,
    "memoryMB": 45.2,
    "networkTxBytes": 15234567,
    "networkRxBytes": 89012345,
    "uptimeSeconds": 16335,
    "goroutines": 34,
    "version": "0.1.0"
  }
}

GET /control/metrics

Returns Prometheus-format metrics for monitoring integrations.

curl http://localhost:4002/control/metrics \
  -H "x-node-secret: my-secret"

Response: 200 OK (text/plain)

# HELP hydra_node_uptime_seconds Node uptime in seconds
# TYPE hydra_node_uptime_seconds gauge
hydra_node_uptime_seconds 16335

# HELP hydra_node_memory_alloc_bytes Go heap allocation in bytes
# TYPE hydra_node_memory_alloc_bytes gauge
hydra_node_memory_alloc_bytes 47394816

# HELP hydra_node_goroutines Active goroutine count
# TYPE hydra_node_goroutines gauge
hydra_node_goroutines 34