Full API Reference

Complete endpoint reference for the Flowtriq REST API v1. For core endpoints (nodes, incidents, channels, workspace), see the REST API page.

Base URL: https://flowtriq.com/api/v1 · Auth: Authorization: Bearer YOUR_DEPLOY_TOKEN · All responses return JSON

Generate a deploy token in Dashboard → Settings → Workspace. The token is a 64-character hex string. Write operations (POST, PATCH, DELETE) require an active subscription.

Common Response Format

All endpoints return a consistent envelope. On success the top-level ok field is true. On error it is false and an error object provides a machine-readable code and human-readable message.

// Success
{ "ok": true, ... }

// Error
{
  "ok": false,
  "error": {
    "code": "invalid_parameter",
    "message": "target_ip is required"
  }
}

Rate limit: 1,000 requests/minute per token. Custom plans can override this limit. See Rate Limits for details.

Mitigation

Manage BGP mitigation rules, adapters, escalation policies, and per-host thresholds. These endpoints power the BGP blackhole, FlowSpec, and cloud scrubbing orchestration layer.

List Active Mitigation Rules

GET/api/v1/mitigation/rules

Returns all currently active mitigation rules across your workspace, including BGP announcements, FlowSpec rules, and cloud scrubbing diversions.

Rule History

GET/api/v1/mitigation/rules/history

Returns historical mitigation rules including withdrawn and expired entries. Useful for audit trails and post-incident review.

Query Parameter	Default	Description
limit	100	Results per page (1–500)

Create Manual BGP Rule

POST/api/v1/mitigation/rules

Manually announce a BGP blackhole or FlowSpec rule through a configured adapter. The rule remains active until explicitly withdrawn or its TTL expires.

Body Parameter	Required	Description
target_ip*	Yes	IP address or prefix to mitigate
intent_type*	Yes	Rule type: `blackhole`, `flowspec`, `scrubbing`
adapter_id*	Yes	ID of the BGP/mitigation adapter to use
ttl	No	Time-to-live in seconds (0 = no expiry)
reason	No	Human-readable reason for the rule

// cURL — Create a blackhole rule
curl -X POST https://flowtriq.com/api/v1/mitigation/rules \
  -H "Authorization: Bearer YOUR_DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_ip": "203.0.113.50/32",
    "intent_type": "blackhole",
    "adapter_id": 1,
    "ttl": 3600,
    "reason": "Manual mitigation for UDP flood"
  }'

// Response 200
{
  "ok": true,
  "rule": {
    "id": 42,
    "target_ip": "203.0.113.50/32",
    "intent_type": "blackhole",
    "status": "active",
    "created_at": "2026-05-12T14:30:00Z"
  }
}

Withdraw Rule

POST/api/v1/mitigation/rules/{id}/withdraw

Withdraws an active mitigation rule, removing the BGP announcement or FlowSpec entry from all peers. This action is immediate.

List Adapters

GET/api/v1/mitigation/adapters

Returns all configured BGP and mitigation adapters in your workspace, including their connection status and capabilities.

Create / Update Adapter

POST/api/v1/mitigation/adapters

Creates a new adapter or updates an existing one. Adapters connect Flowtriq to your BGP speakers, cloud providers, and mitigation appliances.

Body Parameter	Required	Description
adapter_type*	Yes	`exabgp`, `gobgp`, `cloudflare`, `webhook`, `bird2`, `frr`, `radware`, `f5`
name*	Yes	Display name for the adapter
endpoint*	Yes	Connection endpoint (URL or IP:port)
auth_token	No	Authentication token or API key for the adapter
config	No	Adapter-specific configuration object (ASN, communities, etc.)
capabilities	No	Array of supported actions: `blackhole`, `flowspec`, `scrubbing`

// cURL — Create an ExaBGP adapter
curl -X POST https://flowtriq.com/api/v1/mitigation/adapters \
  -H "Authorization: Bearer YOUR_DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "adapter_type": "exabgp",
    "name": "Core Router BGP",
    "endpoint": "10.0.0.1:5000",
    "config": {"local_as": 65001, "communities": ["65001:666"]},
    "capabilities": ["blackhole", "flowspec"]
  }'

// Response 200
{
  "ok": true,
  "adapter": {
    "id": 3,
    "adapter_type": "exabgp",
    "name": "Core Router BGP",
    "status": "configured"
  }
}

Delete Adapter

DELETE/api/v1/mitigation/adapters/{id}

Permanently deletes a mitigation adapter. Any active rules using this adapter will be withdrawn first.

Test Adapter Connectivity

POST/api/v1/mitigation/adapters/{id}/test

Tests connectivity to the adapter endpoint and validates authentication. Returns connection status and latency.

Get Escalation Policy

GET/api/v1/mitigation/escalation

Returns the current escalation policy configuration, including threshold tiers, TTLs, baseline mode, geo lockdown settings, and dry-run status.

Save Escalation Policy

POST/api/v1/mitigation/escalation

Creates or updates the workspace escalation policy. The policy defines how Flowtriq automatically escalates mitigation actions as attack severity increases.

Body Parameter	Required	Description
thresholds	No	Tier-based BPS/PPS thresholds for escalation triggers
ttl	No	Default rule TTL per tier (seconds)
baseline_mode	No	`static` or `dynamic` — how thresholds are calculated
geo_lockdown	No	Geographic lockdown configuration (country codes, action)
dry_run	No	Boolean — log actions without executing them

List Per-Host Thresholds

GET/api/v1/mitigation/thresholds

Returns per-host mitigation thresholds that override the workspace-level escalation policy for specific IPs or prefixes.

Create / Update Threshold

POST/api/v1/mitigation/thresholds

Creates or updates a per-host threshold override. Use this when specific hosts need different mitigation sensitivity than the workspace default.

Body Parameter	Required	Description
target_ip*	Yes	IP address or prefix
label	No	Friendly label for the threshold
thresholds*	Yes	Object with per-tier BPS thresholds (e.g. `{"tier1_bps": 1000000, "tier2_bps": 5000000}`)

Delete Threshold

DELETE/api/v1/mitigation/thresholds/{id}

Removes a per-host threshold override. The host reverts to the workspace escalation policy.

Allowlist

Manage IP allowlist entries that bypass mitigation rules. Allowlisted IPs are never blocked by automated BGP rules, firewall profiles, or scrubbing diversions.

List Allowlist Entries

GET/api/v1/allowlist

Returns all allowlist entries in your workspace. Optionally filter by node to see entries scoped to a specific node.

Query Parameter	Default	Description
node		Filter by node UUID (returns workspace-wide + node-scoped entries)

Add Allowlist Entry

POST/api/v1/allowlist

Adds an IP address or CIDR prefix to the allowlist. Entries can be scoped to the entire workspace or a specific node.

Body Parameter	Required	Description
ip_address*	Yes	IPv4 or IPv6 address, or CIDR prefix
label	No	Friendly label (e.g. “Office VPN”)
scope	No	`workspace` (default) or `node`
node	No	Node UUID (required when scope is `node`)

// cURL — Allowlist an IP
curl -X POST https://flowtriq.com/api/v1/allowlist \
  -H "Authorization: Bearer YOUR_DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": "198.51.100.10",
    "label": "Monitoring Server",
    "scope": "workspace"
  }'

// Response 200
{
  "ok": true,
  "entry": {
    "id": 15,
    "ip_address": "198.51.100.10",
    "label": "Monitoring Server",
    "scope": "workspace"
  }
}

Remove Allowlist Entry

DELETE/api/v1/allowlist/{id}

Permanently removes an allowlist entry. The IP will be subject to mitigation rules again immediately.

Runbooks

Programmatically manage runbooks — automated incident response workflows that execute a sequence of steps when attack conditions are met.

List Runbooks

GET/api/v1/runbooks

Returns all runbooks in your workspace, including execution counts and active/inactive status.

Get Runbook

GET/api/v1/runbooks/{id}

Returns a single runbook with its full step configuration and trigger conditions.

Create Runbook

POST/api/v1/runbooks

Creates a new runbook with trigger conditions and an ordered list of action steps.

Body Parameter	Required	Description
name*	Yes	Runbook display name
description	No	Description of what this runbook does
trigger_conditions*	Yes	Object defining when the runbook fires (attack family, severity, PPS threshold, etc.)
steps*	Yes	Ordered array of step objects

Each step object has action_type and action_config. Valid step types:

action_type	Description
wait	Pause execution for a specified duration
iptables	Apply or remove iptables/nftables rules on the node
notify_channel	Send a notification to a configured alert channel
webhook	Fire an HTTP request to an external URL
cloudflare_uam	Enable Cloudflare Under Attack Mode
scrubbing_enable	Activate a cloud scrubbing integration
log	Write a message to the runbook execution log
condition	Conditional branch — execute subsequent steps only if condition is met

// cURL — Create a runbook
curl -X POST https://flowtriq.com/api/v1/runbooks \
  -H "Authorization: Bearer YOUR_DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auto-mitigate UDP floods",
    "description": "Block UDP flood traffic and notify the team",
    "trigger_conditions": {
      "family": "udp_flood",
      "severity": "critical",
      "min_pps": 500000
    },
    "steps": [
      {"action_type": "log", "action_config": {"message": "UDP flood detected, starting mitigation"}},
      {"action_type": "iptables", "action_config": {"cmd": "block_udp_flood"}},
      {"action_type": "wait", "action_config": {"seconds": 30}},
      {"action_type": "notify_channel", "action_config": {"channel_id": 5}}
    ]
  }'

// Response 200
{
  "ok": true,
  "runbook": {
    "id": 7,
    "name": "Auto-mitigate UDP floods",
    "active": true,
    "steps_count": 4
  }
}

Update Runbook

PATCH/api/v1/runbooks/{id}

Updates an existing runbook. Only include the fields you want to change. Steps can be replaced entirely or left unchanged.

Delete Runbook

DELETE/api/v1/runbooks/{id}

Permanently deletes a runbook. Any in-progress executions will complete but no new executions will start.

Toggle Runbook

POST/api/v1/runbooks/{id}/toggle

Toggles a runbook between active and inactive. Inactive runbooks are preserved but will not trigger on new incidents.

Manual Test Run

POST/api/v1/runbooks/{id}/run

Triggers a manual test execution of a runbook. Useful for validating step configuration before going live.

Body Parameter	Required	Description
node	No	Node UUID to run against (uses a synthetic test context if omitted)

Execution History

GET/api/v1/runbooks/{id}/executions

Returns the execution history for a runbook, including step-by-step results, timing, and success/failure status.

PCAPs

Retrieve and download packet captures collected by ftagent during incidents. PCAPs provide full packet-level forensic data for attack analysis.

List PCAP Captures

GET/api/v1/pcaps

Returns a paginated list of PCAP captures across your workspace, ordered by capture time (newest first).

Query Parameter	Default	Description
limit	50	Results per page (1–100)
offset	0	Pagination offset

List Parsed Packets

GET/api/v1/pcaps/{id}/packets

Returns parsed packet metadata from a PCAP capture, including source/destination IPs, ports, protocols, and payload sizes.

Query Parameter	Default	Description
limit	100	Packets per page (1–1000)
offset	0	Pagination offset

Forensic Analysis

GET/api/v1/pcaps/{id}/analysis

Returns cached AI-generated forensic analysis of the PCAP, including attack vector classification, source IP distribution, and recommended mitigation actions.

// cURL — Get PCAP analysis
curl -H "Authorization: Bearer YOUR_DEPLOY_TOKEN" \
  https://flowtriq.com/api/v1/pcaps/42/analysis

// Response 200
{
  "ok": true,
  "analysis": {
    "attack_vector": "DNS amplification",
    "total_packets": 284501,
    "unique_sources": 1847,
    "top_source_countries": ["CN", "RU", "BR"],
    "summary": "DNS amplification attack using open resolvers..."
  }
}

Download PCAP File

GET/api/v1/pcaps/{id}/download

Downloads the raw PCAP file in binary format. The response content type is application/vnd.tcpdump.pcap. Open with Wireshark, tcpdump, or any packet analysis tool.

// cURL — Download PCAP to file
curl -H "Authorization: Bearer YOUR_DEPLOY_TOKEN" \
  -o capture.pcap \
  https://flowtriq.com/api/v1/pcaps/42/download

Scrubbing

Manage cloud scrubbing integrations that divert traffic through upstream cleaning providers during attacks. For configuration guides, see Cloud Scrubbing.

Supported integration types: cloudflare_magic_transit, ovh_mitigation, hetzner_mitigation, cloudflare_waf, digitalocean, vultr, aws_shield, linode

List Scrubbing Integrations

GET/api/v1/scrubbing

Returns all configured scrubbing integrations with their current status and provider details.

Get Integration Status

GET/api/v1/scrubbing/{id}/status

Returns the real-time status of a scrubbing integration, including whether traffic is currently being diverted and connection health.

Test Integration

POST/api/v1/scrubbing/{id}/test

Tests connectivity and authentication with the upstream scrubbing provider. Returns success/failure and latency.

Announce / Enable Scrubbing

POST/api/v1/scrubbing/{id}/announce

Activates the scrubbing integration, diverting traffic through the upstream provider for cleaning. The exact mechanism depends on the provider (BGP announcement, API call, tunnel activation, etc.).

Withdraw / Disable Scrubbing

POST/api/v1/scrubbing/{id}/withdraw

Deactivates the scrubbing integration, returning traffic to its normal direct path. Use after an attack has subsided.

// cURL — Announce scrubbing for an integration
curl -X POST https://flowtriq.com/api/v1/scrubbing/3/announce \
  -H "Authorization: Bearer YOUR_DEPLOY_TOKEN"

// Response 200
{
  "ok": true,
  "status": "active",
  "provider": "cloudflare_magic_transit",
  "message": "Traffic diversion activated"
}

// cURL — Withdraw scrubbing
curl -X POST https://flowtriq.com/api/v1/scrubbing/3/withdraw \
  -H "Authorization: Bearer YOUR_DEPLOY_TOKEN"

// Response 200
{
  "ok": true,
  "status": "inactive",
  "message": "Traffic diversion withdrawn"
}

Attack Profiles

Apply pre-built firewall rule sets optimized for specific deployment types. Profiles contain curated iptables/nftables rules tuned for the traffic patterns of each environment.

Apply Firewall Profile

POST/api/v1/attack-profiles/apply

Pushes a firewall profile to one or more nodes. The agent applies the rules using the specified firewall suite. Pass ["all"] as node_ids to deploy to every node in your workspace.

Body Parameter	Required	Description
profile_id*	Yes	Profile identifier (see list below)
suite*	Yes	Firewall backend: `iptables`, `nftables`, `ufw`, `firewalld`
node_ids*	Yes	Array of node UUIDs, or `["all"]` for all nodes
rules	No	Optional custom rules array, each with `cmd` and `title`

Available profile IDs:

profile_id	Optimized For
game_server	Game servers (Minecraft, FiveM, Rust, CS2, etc.)
hosting_provider	Shared/reseller hosting providers
isp	Internet service providers and transit networks
saas	SaaS applications (web-heavy TCP traffic)
ecommerce	E-commerce platforms (payment flow protection)
fintech	Financial services (strict ingress filtering)
small_operator	Small operators and VPS providers
msp	Managed service providers
edge_node	Edge/CDN nodes and reverse proxies
router	Software routers and gateways
game_studio	Game studios (development + production servers)

// cURL — Apply game_server profile to specific nodes
curl -X POST https://flowtriq.com/api/v1/attack-profiles/apply \
  -H "Authorization: Bearer YOUR_DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "game_server",
    "suite": "nftables",
    "node_ids": ["a1b2c3d4-...", "e5f6a7b8-..."]
  }'

// Response 200
{
  "ok": true,
  "applied_to": 2,
  "profile": "game_server",
  "suite": "nftables"
}