Hydra
API Reference

Read and update node configuration via the control plane.

Configuration API

Manage the node's YAML configuration through the control plane API. All endpoints require control-plane authentication.

GET /control/config

Read the current node configuration.

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

Response: 200 OK

{
  "config": {
    "server": {
      "port": 4001,
      "host": "0.0.0.0"
    },
    "control": {
      "port": 4002,
      "host": "127.0.0.1"
    },
    "mode": "public",
    "sources": {
      "adsb": { "enabled": true, "interval": "60s" },
      "ais": { "enabled": true },
      "oref": { "enabled": true, "interval": "3s" },
      "cyber": { "enabled": true, "interval": "5m" },
      "usgs": { "enabled": true, "interval": "5m" },
      "airspace": { "enabled": false },
      "telegram": { "enabled": false },
      "xtracker": { "enabled": false },
      "polymarket": { "enabled": true, "interval": "15m" },
      "maritime": { "enabled": false }
    }
  },
  "yaml": "node:\n  name: hydra-node-us-east-1\n  ..."
}

Note: The node.secret field is always zeroed in the response — it is never exposed via the API.

Raw YAML format

curl "http://localhost:4002/control/config?format=raw" \
  -H "x-node-secret: my-secret"

Response: 200 OK

{
  "yaml": "mode: public\nserver:\n  port: 4001\n  host: 0.0.0.0\ncontrol:\n  port: 4002\n  host: 127.0.0.1\nsources:\n  adsb:\n    enabled: true\n    interval: 60s\n  ..."
}

PUT /control/config

Replace the entire node configuration with new YAML.

curl -X PUT http://localhost:4002/control/config \
  -H "x-node-secret: my-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "yaml": "mode: public\nserver:\n  port: 4001\n  host: 0.0.0.0\nsources:\n  adsb:\n    enabled: true\n    interval: 60s",
    "restart": true
  }'

Request Body:

Field Type Required Description
yaml string Yes Full YAML configuration
restart boolean No Restart the node after saving (default: false)

Response: 200 OK

{
  "status": "saved"
}

The YAML is validated before saving. If invalid, returns 400 Bad Request.

PATCH /control/config

Partially update source configuration. Only specified fields are merged — unset fields remain unchanged.

curl -X PATCH http://localhost:4002/control/config \
  -H "x-node-secret: my-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": {
      "adsb": {
        "interval": "30s"
      },
      "cyber": {
        "enabled": true,
        "interval": "3m"
      },
      "telegram": {
        "enabled": true,
        "channels": ["militarytracker", "intelanon"]
      }
    },
    "restart": true
  }'

Request Body:

Field Type Description
sources object Partial source configuration map
restart boolean Restart after saving

Source Configuration Fields:

Field Type Description
enabled boolean Enable/disable the source
interval string Polling interval (Go duration: 30s, 5m, 1h)
flushInterval string Buffer flush interval
apiKeyEnv string Environment variable name for API key
apiHostEnv string Environment variable name for API host
openaipKeyEnv string Environment variable for OpenAIP key
proxyUrl string HTTP proxy URL
accounts string[] X/Twitter accounts to track
cookies string[] Authentication cookies
channels string[] Telegram channels to monitor
marketInterval string Market-specific polling interval

Valid source names: usgs, adsb, ais, oref, cyber, airspace, xtracker, telegram, polymarket, maritime

Response: 200 OK

{
  "status": "saved"
}

Example: Enable all sources

curl -X PATCH http://localhost:4002/control/config \
  -H "x-node-secret: my-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": {
      "adsb": { "enabled": true },
      "ais": { "enabled": true },
      "oref": { "enabled": true },
      "cyber": { "enabled": true },
      "usgs": { "enabled": true },
      "airspace": { "enabled": true },
      "telegram": { "enabled": true },
      "xtracker": { "enabled": true },
      "polymarket": { "enabled": true },
      "maritime": { "enabled": true }
    },
    "restart": true
  }'

Example: Configure Telegram channels

curl -X PATCH http://localhost:4002/control/config \
  -H "x-node-secret: my-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": {
      "telegram": {
        "enabled": true,
        "channels": ["militarytracker", "intelanon", "conflicts"],
        "interval": "2m"
      }
    }
  }'