Agent API Reference
These endpoints are used by the FTAgent running on your server. They authenticate with two headers:
Authorization: Bearer your-node-api-key
X-Node-UUID: your-node-uuid
Base URL: https://flowtriq.com/api/v1/agent
Heartbeat
POST/v1/agent/heartbeat
Sent every 30 seconds to indicate the agent is online. Updates last_seen_at and status.
| Parameter | Type | Description |
|---|---|---|
| agent_version | string | Current agent version |
| uptime | integer | Agent uptime in seconds |
| os | string | OS identifier (e.g., "Ubuntu 22.04") |
Submit Metrics
POST/v1/agent/metrics
Submits PPS/BPS samples. The agent sends one batch per second.
| Parameter | Type | Description |
|---|---|---|
| pps* | integer | Packets per second |
| bps* | integer | Bits per second |
| tcp_pct | float | TCP percentage (0-100) |
| udp_pct | float | UDP percentage (0-100) |
| icmp_pct | float | ICMP percentage (0-100) |
| conn_count | integer | Active connections |
| recorded_at | string | ISO 8601 timestamp |
Report Incident
POST/v1/agent/incident
Opens or updates an incident when the agent detects an attack threshold crossing.
| Parameter | Type | Description |
|---|---|---|
| attack_family* | string | Detected family: udp_flood, syn_flood, http_flood, icmp_flood, dns_flood, tcp_flood, protocol_flood, multi_vector, unknown |
| severity* | string | low, medium, high, critical |
| peak_pps | integer | Peak packets/sec observed |
| peak_bps | integer | Peak bits/sec observed |
| protocol_breakdown | object | {"tcp": 15.2, "udp": 82.1, "icmp": 2.7} |
| tcp_flag_breakdown | object | {"SYN": 1200, "ACK": 400, "RST": 50} |
| geo_breakdown | object | {"US": 4200, "CN": 1800, "RU": 920} |
| source_ip_count | integer | Unique source IPs |
| top_src_ips | array | [{"ip": "1.2.3.4", "count": 5000}, ...] |
| top_dst_ports | array | [{"port": 80, "count": 12000}, ...] |
| ioc_matches | array | Matched IOC patterns |
| spoofing_detected | boolean | TTL analysis indicates spoofed sources |
| botnet_detected | boolean | Traffic pattern matches known botnet signatures |
Upload PCAP
POST/v1/agent/pcap
Uploads a PCAP capture file for an incident. Multipart form upload, max 100 MB.
| Parameter | Type | Description |
|---|---|---|
| incident_id* | integer | Associated incident ID |
| file* | file | PCAP file (multipart upload) |
Get Config
GET/v1/agent/config
Returns the node's remote config including IOC patterns, thresholds, and pending commands.
// Response 200
{
"node_id": 1,
"pps_threshold": 50000,
"baseline": { "p99_pps": 12000, "mean_pps": 3400 },
"ioc_patterns": [...],
"pending_commands": [
{ "id": 5, "command": "iptables -I INPUT -s 1.2.3.4 -j DROP" }
]
}