Hydra
API Reference

Complete API reference for the open-source Hydra Node.

Node API Reference

The Hydra Node is an open-source Go binary that collects intelligence data from 10+ sources and serves it via HTTP and WebSocket APIs. Every node runs its own local API server.

This reference documents all endpoints — public, authenticated, and control plane — since the node is fully open source.

Base URL

Each node runs on its own address. For managed nodes:

https://node-{id}.{region}.hydra.fast

For self-hosted nodes, the defaults are:

http://localhost:4001          # Public + Authenticated API
http://localhost:4002          # Control Plane (localhost only)

Authentication

The node has three authentication levels:

Level Method Endpoints Default Port
Public None /health, /status, /public/* 4001
API Key x-api-key header or ?apiKey= query /v1/* endpoints 4001
Control x-node-secret header or HMAC signature /control/* endpoints 4002

The control plane binds to 127.0.0.1 only by default — it is not exposed externally.

API Key Authentication

curl http://localhost:4001/v1/signals \
  -H "x-api-key: hyd_a1b2c3d4..."

Or via query parameter:

curl "http://localhost:4001/v1/signals?apiKey=hyd_a1b2c3d4..."

Control Plane Authentication

Option 1 — Raw secret:

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

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

curl http://localhost:4002/control/status \
  -H "x-control-hmac: <HMAC-SHA256 signature>" \
  -H "x-control-timestamp: <unix timestamp>"

Endpoint Overview

Public (no auth)

Method Path Description
GET /health Health check
GET /status Node version and uptime
GET /status/sources Data source status
GET /public/signals Recent signals (max 50)
GET /public/aircraft Aircraft positions (thinned)
GET /public/vessels Vessel positions
GET /public/markets Prediction markets

Authenticated (API key)

Method Path Description
GET /v1/signals Full signal data with filters
GET /v1/aircraft Full aircraft data
GET /v1/vessels Full vessel data
GET /v1/markets Full market data

WebSocket Streaming

Path Auth Description
/stream/live None Public real-time stream
/v1/stream API key Scoped real-time stream

Control Plane (node secret)

Method Path Description
GET /control/status Detailed node status with metrics
POST /control/restart Restart the node
POST /control/restart-source/{name} Restart a specific source
POST /control/source/{name}/enable Enable a source
POST /control/source/{name}/disable Disable a source
GET /control/logs Retrieve log entries
GET /control/logs/stream WebSocket log stream
GET /control/metrics Prometheus metrics
GET /control/config Read node configuration
PUT /control/config Replace full configuration
PATCH /control/config Partial config update
GET /control/api-keys List API keys
POST /control/api-keys Create API key
DELETE /control/api-keys/{id} Revoke API key