Schemas

Download schema

Action

id

string · required

Formatted action ID.

Example: action_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

result

ActionResult · required

Action result applied to a matching request.

status_code

integer | null · required

HTTP status returned by results that produce a response.

message

string | null · required

Response message returned by results that produce a response.

window_seconds

integer | null · required

Rate-limit window in seconds, or null for other results.

requests_per_window

integer | null · required

Requests allowed per rate-limit window, or null for other results.

partition_by

array | null · required

Rate-limit partition dimensions, an empty list for one rule-wide bucket, or null when unset (per client IP on current proxies, rule-derived on older proxies).

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 last-update timestamp.

rules_count

integer

Number of rules currently using this action.

ActionResult

string

BehaviorMetric

string

IPList

id

string · required

Formatted IP list ID accepted by IP-list rule conditions.

Example: iplist_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

is_global

boolean · required

Whether the list is managed globally instead of by the authenticated team.

supports_confidence

boolean · required

Whether IP-list rule matches may specify a confidence threshold.

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 last-update timestamp.

entries_count

integer

Number of entries in the list when requested by the endpoint.

IPListEntry

id

string · required

Formatted IP-list entry ID.

Example: iplist_entry_01j8q8zk2f4m6n7p9r1s3t5v7x

content

string · required

Normalized IPv4, IPv6, or CIDR value.

type

IPListEntryType · required

Entry address type.

comment

string | null · required

Optional note associated with the entry.

confidence

integer | null · required

Confidence assigned by a managed list, or null for custom lists.

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 last-update timestamp.

IPListEntryType

integer

ImportIPListEntriesRequest

object[] · minItems: 1 · maxItems: 1000 · required

Entries to normalize and add to the custom IP list.

LogWindowAnchorType

string

LogWindowRequest

object · required

Anchor used to center the returned log window.

before

integer · min: 0 · max: 200 · required

Number of matching events to retrieve before the anchor.

after

integer · min: 0 · max: 200 · required

Number of matching events to retrieve after the anchor.

object · required

ProxyRelease

version

string · required

tag

string · required

url

string · required

Release notes on GitHub.

is_latest

boolean · required

Whether this is the newest release, the one manual upgrades install.

published_at

string · required

ISO 8601 timestamp of when the release was published.

rollout_starts_at

string · required

ISO 8601 timestamp of when the automatic rollout starts upgrading to this release.

ProxyUpgrade

id

string · required

Formatted upgrade ID.

Example: upgrade_01j8q8zk2f4m6n7p9r1s3t5v7x

status

ProxyUpgradeStatus · required

running until the server reports the target version, which makes it succeeded. It is failed when the server did not report it in time.

source

ProxyUpgradeSource · required

Whether someone started the upgrade or the automatic rollout did.


`manual` Started by someone, from the UI or the API.
`automatic` Started by the automatic rollout.

from_version

string | null · required

Proxy version when the upgrade started.

target_version

string · required

Proxy version the upgrade installs.

failure

string | null · required

Why the upgrade failed: timeout when the server did not report the target version in time.

created_at

string · required

ISO 8601 timestamp of when the upgrade started.

finished_at

string | null · required

ISO 8601 timestamp of when the upgrade succeeded or failed.

ProxyUpgradeSource

string


`manual` Started by someone, from the UI or the API.
`automatic` Started by the automatic rollout.

ProxyUpgradeStatus

string

QueryLogsRequest

from

string · date-time · required

Inclusive beginning of the query range. Defaults to 24 hours before to.

Example: 2026-09-02T12:00:00Z

to

string · date-time · required

Exclusive end of the query range. Defaults to the current time.

Example: 2026-09-03T12:00:00Z

direction

string · enum · required

Sort order for matching events.

Enum values:

asc

desc

Example: desc

Default: desc

limit

integer · min: 1 · max: 200 · required

Maximum number of events to return.

Default: 100

object · required

cursor

string | null · maxLength: 2048

Opaque cursor returned as meta.next_cursor by the previous page. Keep the time range, filters, and direction unchanged when continuing a query.

Example: eyJ0aW1lc3RhbXAiOjE3NzczNzQwMDAwMDAsImlkIjoic3ludGhldGljLWV2ZW50In0=

RateLimitPartition

string

Rule

id

string · required

Formatted rule ID.

Example: rule_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

position

integer · required

Zero-based evaluation position. Lower positions are evaluated first.

action_id

string | null · required

Formatted action ID, or null when the rule has no action.

object · required

Normalized recursive condition group evaluated by the rule.

object · required

Server scope controlling which proxies evaluate the rule.

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 last-update timestamp.

RuleCondition

string

RuleMatch

string

RuleServerScopeMode

string

RuleType

string

SaveActionRequest

name

string · maxLength: 255 · required

Human-readable action name.

Example: Block synthetic scanners

result

string · enum · required

Result applied when a rule using this action matches. log and skip_log continue evaluation; skip_log leaves the request out of the logs unless another rule acts on it or the response status is 400 or higher.

Enum values:

allow

block

challenge

rate_limit

log

skip_log

status_code

integer | null · min: 100 · max: 599

HTTP status returned by results that produce a response.

message

string | null · maxLength: 255

Response message returned by results that produce a response.

window_seconds

integer | null · min: 1 · max: 86400

Rate-limit window in seconds. Required when result is rate_limit.

requests_per_window

integer | null · min: 1

Requests allowed during the rate-limit window. Required when result is rate_limit.

partition_by

array | null · maxItems: 5 · unique

Dimensions that receive independent rate-limit buckets. An empty list creates one bucket per rule. Null leaves the scope to the proxy: per client IP on current proxies, a rule-derived bucket shared by all clients on older proxies.

Enum values:

client.ip

connection.id

request.fingerprint.ja4

request.url.domain

request.url.path

SaveIPListEntryRequest

content

string · maxLength: 255 · required

IPv4, IPv6, or CIDR value.

Example: 198.51.100.24

comment

string | null · maxLength: 255 · required

Optional note associated with the entry.

SaveIPListRequest

name

string · maxLength: 255 · required

Human-readable IP-list name.

Example: Synthetic blocked networks

SaveRuleRequest

name

string · maxLength: 255 · required

Human-readable rule name.

Example: Protect synthetic service

object · required

Recursive condition group. Each group contains an AND or OR operator, a list of matches, and nested groups. Consult the rule capabilities endpoint for supported match types and operators.

Example: {"operator":"AND","matches":[{"type":"domain","match":"equals","value":"service.example.test"}],"groups":[]}

object · required

Server scope controlling which proxies evaluate the rule.

action_id

string | null

Formatted ID of an action owned by the authenticated team. Send null for a match-only rule.

position

integer · min: 0

Zero-based evaluation position. Omit when creating to append the rule; omit when updating to retain its current position.

Example: 0

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.

Server

id

string · required

Formatted server ID accepted by rule server scopes.

Example: server_01j8q8zk2f4m6n7p9r1s3t5v7x

name

string · required

deployment

ServerDeployment · required

Whether the proxy runs on a single host or as a fleet of instances sharing one key.

live_instance_count

integer · required

Number of proxy instances that reported in during the last 7 minutes.

version

string | null · required

Currently reported FlowGuard proxy version.

heartbeat_status

string | null · required

Health status calculated from the proxy's latest heartbeat.

config_up_to_date

boolean · required

Whether the proxy has loaded the latest desired configuration.

default_hostname

string | null · required

Default TLS hostname, or null when unmatched connections are rejected.

cert_path

string | null · required

Absolute path containing combined certificate files.

acme_path

string | null · required

Absolute path to a Traefik ACME file.

nginx_config_path

string | null · required

Absolute path to an NGINX configuration file.

allow_unattended_upgrades

boolean · required

Whether FlowGuard may initiate proxy upgrades.

object · required

Proxy upgrades started from FlowGuard.

object · required

HTTP protocols served by the proxy.

object · required

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

fail2ban_enabled

boolean · required

Whether the host-level Fail2Ban integration is enabled.

object · required

Rule features supported by the installed proxy version.

created_at

string · required

ISO 8601 creation timestamp.

updated_at

string · required

ISO 8601 last-update timestamp.

ServerDeployment

string

SummarizeTrafficRequest

from

string · date-time · required

to

string · date-time · required

baselines

TrafficBaseline[] · maxItems: 2 · unique · required

Enum values:

previous_period

previous_day

object · required

TrafficBaseline

string · enum

Enum values:

previous_period

previous_day