Servers

Download schema

Endpoints for discovering the FlowGuard proxies available to rules.

List servers

GET

https://flowguard.network/api/v1

/servers

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the authenticated team's FlowGuard proxies and their rule capabilities. Use the formatted server IDs when creating an include or exclude rule scope. Proxy credentials and configuration are not exposed.

List servers › query Parameters

query

string | null · maxLength: 255

Search results by name.

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

List servers › Responses

Array of Server

Server[] · required

GET/servers

curl https://flowguard.network/api/v1/servers \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "Synthetic edge",
      "deployment": "host",
      "live_instance_count": 0,
      "version": "version",
      "heartbeat_status": "heartbeat_status",
      "config_up_to_date": true,
      "default_hostname": "default_hostname",
      "cert_path": "cert_path",
      "acme_path": "acme_path",
      "nginx_config_path": "nginx_config_path",
      "allow_unattended_upgrades": true,
      "upgrades": {
        "automatic": true,
        "follows_team": true,
        "latest": {
          "id": "upgrade_01j8q8zk2f4m6n7p9r1s3t5v7x",
          "status": "running",
          "source": "manual",
          "from_version": "from_version",
          "target_version": "target_version",
          "failure": "failure",
          "created_at": "created_at",
          "finished_at": "finished_at"
        }
      },
      "protocols": {
        "http1": true,
        "http2": true,
        "http3": true,
        "advertise_http3": true
      },
      "upstream_headers": {
        "stream_id": true,
        "ip_country": true
      },
      "fail2ban_enabled": true,
      "capabilities": {
        "server_config": true,
        "challenge_actions": true,
        "skip_log_actions": true,
        "proxy_matchers": true,
        "acme_path": true,
        "upstream_client_ip_config": true,
        "fail2ban": true,
        "upstream_headers": true,
        "rate_limit_partitions": true,
        "behavior_matchers": true,
        "user_agent_presence_matchers": true,
        "remote_upgrade": true
      },
      "created_at": "created_at",
      "updated_at": "updated_at"
    }
  ]
}

json

application/json

Create a server

POST

https://flowguard.network/api/v1

/servers

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Create a FlowGuard proxy record for the authenticated team. Setup credentials remain available only in the web application.

Create a server › Request Body

SaveServerRequest

name

string · maxLength: 255 · required

Human-readable proxy name.

Example: Synthetic edge proxy

deployment

string · enum

Whether the proxy runs on a single host or as a fleet of instances sharing one key. Can only be set when creating the server.

Enum values:

host

fleet

default_hostname

string | null · maxLength: 255

Default TLS hostname, or null to reject connections without a matching certificate.

cert_path

string | null · maxLength: 255

Absolute path containing combined certificate files.

acme_path

string | null · maxLength: 255

Absolute path to a Traefik ACME file.

nginx_config_path

string | null · maxLength: 255

Absolute path to an NGINX configuration file.

allow_unattended_upgrades

boolean

Allow upgrades initiated by FlowGuard.

auto_upgrades

boolean | null

Whether the automatic rollout upgrades this server, or null to follow the team's setting. Omit it to keep the current value.

object

Protocol configuration applied by the proxy.

object

FG-Stream and FG-IPCountry headers the proxy adds to requests sent to the backend.

fail2ban_enabled

boolean

Enable the host-level Fail2Ban integration.

Create a server › Responses

The server was created.

Server · required

POST/servers

curl https://flowguard.network/api/v1/servers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Synthetic edge proxy",
  "deployment": "host",
  "default_hostname": "default_hostname",
  "cert_path": "cert_path",
  "acme_path": "acme_path",
  "nginx_config_path": "nginx_config_path",
  "allow_unattended_upgrades": true,
  "auto_upgrades": true,
  "protocols": {
    "http1": true,
    "http2": true,
    "http3": true,
    "advertise_http3": true
  },
  "upstream_headers": {
    "stream_id": true,
    "ip_country": true
  },
  "fail2ban_enabled": true
}'

Example Request Body

{
  "name": "Synthetic edge proxy",
  "deployment": "host",
  "default_hostname": "default_hostname",
  "cert_path": "cert_path",
  "acme_path": "acme_path",
  "nginx_config_path": "nginx_config_path",
  "allow_unattended_upgrades": true,
  "auto_upgrades": true,
  "protocols": {
    "http1": true,
    "http2": true,
    "http3": true,
    "advertise_http3": true
  },
  "upstream_headers": {
    "stream_id": true,
    "ip_country": true
  },
  "fail2ban_enabled": true
}

json

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Synthetic edge",
    "deployment": "host",
    "live_instance_count": 0,
    "version": "version",
    "heartbeat_status": "heartbeat_status",
    "config_up_to_date": true,
    "default_hostname": "default_hostname",
    "cert_path": "cert_path",
    "acme_path": "acme_path",
    "nginx_config_path": "nginx_config_path",
    "allow_unattended_upgrades": true,
    "upgrades": {
      "automatic": true,
      "follows_team": true,
      "latest": {
        "id": "upgrade_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "status": "running",
        "source": "manual",
        "from_version": "from_version",
        "target_version": "target_version",
        "failure": "failure",
        "created_at": "created_at",
        "finished_at": "finished_at"
      }
    },
    "protocols": {
      "http1": true,
      "http2": true,
      "http3": true,
      "advertise_http3": true
    },
    "upstream_headers": {
      "stream_id": true,
      "ip_country": true
    },
    "fail2ban_enabled": true,
    "capabilities": {
      "server_config": true,
      "challenge_actions": true,
      "skip_log_actions": true,
      "proxy_matchers": true,
      "acme_path": true,
      "upstream_client_ip_config": true,
      "fail2ban": true,
      "upstream_headers": true,
      "rate_limit_partitions": true,
      "behavior_matchers": true,
      "user_agent_presence_matchers": true,
      "remote_upgrade": true
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Show a server

GET

https://flowguard.network/api/v1

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Show one FlowGuard proxy belonging to the authenticated team, including its desired configuration, health, and capabilities. Credentials are never exposed.

Show a server › path Parameters

server

string · required

Show a server › Responses

Server

Server · required

GET/servers/{server}

curl https://flowguard.network/api/v1/servers/:server \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Synthetic edge",
    "deployment": "host",
    "live_instance_count": 0,
    "version": "version",
    "heartbeat_status": "heartbeat_status",
    "config_up_to_date": true,
    "default_hostname": "default_hostname",
    "cert_path": "cert_path",
    "acme_path": "acme_path",
    "nginx_config_path": "nginx_config_path",
    "allow_unattended_upgrades": true,
    "upgrades": {
      "automatic": true,
      "follows_team": true,
      "latest": {
        "id": "upgrade_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "status": "running",
        "source": "manual",
        "from_version": "from_version",
        "target_version": "target_version",
        "failure": "failure",
        "created_at": "created_at",
        "finished_at": "finished_at"
      }
    },
    "protocols": {
      "http1": true,
      "http2": true,
      "http3": true,
      "advertise_http3": true
    },
    "upstream_headers": {
      "stream_id": true,
      "ip_country": true
    },
    "fail2ban_enabled": true,
    "capabilities": {
      "server_config": true,
      "challenge_actions": true,
      "skip_log_actions": true,
      "proxy_matchers": true,
      "acme_path": true,
      "upstream_client_ip_config": true,
      "fail2ban": true,
      "upstream_headers": true,
      "rate_limit_partitions": true,
      "behavior_matchers": true,
      "user_agent_presence_matchers": true,
      "remote_upgrade": true
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Update a server

PATCH

https://flowguard.network/api/v1

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Update a FlowGuard proxy belonging to the authenticated team. Omitted fields retain their current values, and null clears nullable path and hostname fields.

Update a server › path Parameters

server

string · required

Update a server › Request Body

SaveServerRequest

name

string · maxLength: 255 · required

Human-readable proxy name.

Example: Synthetic edge proxy

deployment

string · enum

Whether the proxy runs on a single host or as a fleet of instances sharing one key. Can only be set when creating the server.

Enum values:

host

fleet

default_hostname

string | null · maxLength: 255

Default TLS hostname, or null to reject connections without a matching certificate.

cert_path

string | null · maxLength: 255

Absolute path containing combined certificate files.

acme_path

string | null · maxLength: 255

Absolute path to a Traefik ACME file.

nginx_config_path

string | null · maxLength: 255

Absolute path to an NGINX configuration file.

allow_unattended_upgrades

boolean

Allow upgrades initiated by FlowGuard.

auto_upgrades

boolean | null

Whether the automatic rollout upgrades this server, or null to follow the team's setting. Omit it to keep the current value.

object

Protocol configuration applied by the proxy.

object

FG-Stream and FG-IPCountry headers the proxy adds to requests sent to the backend.

fail2ban_enabled

boolean

Enable the host-level Fail2Ban integration.

Update a server › Responses

Server

Server · required

PATCH/servers/{server}

curl https://flowguard.network/api/v1/servers/:server \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Synthetic edge proxy",
  "deployment": "host",
  "default_hostname": "default_hostname",
  "cert_path": "cert_path",
  "acme_path": "acme_path",
  "nginx_config_path": "nginx_config_path",
  "allow_unattended_upgrades": true,
  "auto_upgrades": true,
  "protocols": {
    "http1": true,
    "http2": true,
    "http3": true,
    "advertise_http3": true
  },
  "upstream_headers": {
    "stream_id": true,
    "ip_country": true
  },
  "fail2ban_enabled": true
}'

Example Request Body

{
  "name": "Synthetic edge proxy",
  "deployment": "host",
  "default_hostname": "default_hostname",
  "cert_path": "cert_path",
  "acme_path": "acme_path",
  "nginx_config_path": "nginx_config_path",
  "allow_unattended_upgrades": true,
  "auto_upgrades": true,
  "protocols": {
    "http1": true,
    "http2": true,
    "http3": true,
    "advertise_http3": true
  },
  "upstream_headers": {
    "stream_id": true,
    "ip_country": true
  },
  "fail2ban_enabled": true
}

json

Example Responses

{
  "data": {
    "id": "server_01j8q8zk2f4m6n7p9r1s3t5v7x",
    "name": "Synthetic edge",
    "deployment": "host",
    "live_instance_count": 0,
    "version": "version",
    "heartbeat_status": "heartbeat_status",
    "config_up_to_date": true,
    "default_hostname": "default_hostname",
    "cert_path": "cert_path",
    "acme_path": "acme_path",
    "nginx_config_path": "nginx_config_path",
    "allow_unattended_upgrades": true,
    "upgrades": {
      "automatic": true,
      "follows_team": true,
      "latest": {
        "id": "upgrade_01j8q8zk2f4m6n7p9r1s3t5v7x",
        "status": "running",
        "source": "manual",
        "from_version": "from_version",
        "target_version": "target_version",
        "failure": "failure",
        "created_at": "created_at",
        "finished_at": "finished_at"
      }
    },
    "protocols": {
      "http1": true,
      "http2": true,
      "http3": true,
      "advertise_http3": true
    },
    "upstream_headers": {
      "stream_id": true,
      "ip_country": true
    },
    "fail2ban_enabled": true,
    "capabilities": {
      "server_config": true,
      "challenge_actions": true,
      "skip_log_actions": true,
      "proxy_matchers": true,
      "acme_path": true,
      "upstream_client_ip_config": true,
      "fail2ban": true,
      "upstream_headers": true,
      "rate_limit_partitions": true,
      "behavior_matchers": true,
      "user_agent_presence_matchers": true,
      "remote_upgrade": true
    },
    "created_at": "created_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Delete a server

DELETE

https://flowguard.network/api/v1

/servers/{server}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Delete a FlowGuard proxy record belonging to the authenticated team. The proxy installation must be removed separately from its host.

Delete a server › path Parameters

server

string · required

Delete a server › Responses

The server was deleted.

string

Upgrade a server

POST

https://flowguard.network/api/v1

/servers/{server}/upgrade

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Ask the server's proxy to install the newest release right away, without waiting for the automatic rollout. The upgrade stays running until the server reports the new version, and fails when it does not within 10 minutes. A running upgrade is returned instead of starting another. The server must allow upgrades, be online and run a single host outside Caddy.

Upgrade a server › path Parameters

server

string · required

Upgrade a server › Responses

Const value: 202

List proxy releases

GET

https://flowguard.network/api/v1

/proxy-releases

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the stable FlowGuard proxy releases, newest first, with when the automatic rollout starts upgrading to each of them. Filter with query on a version prefix, such as 0.31.

List proxy releases › query Parameters

query

string | null · maxLength: 255

Search results by name.

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

List proxy releases › Responses

Paginated set of ProxyRelease

ProxyRelease[] · required

object · required

Actions IP Lists