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": "deployment",
      "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,
      "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.

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,
  "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,
  "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": "deployment",
    "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,
    "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": "deployment",
    "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,
    "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.

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,
  "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,
  "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": "deployment",
    "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,
    "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

Actions IP Lists