{ "openapi": "3.1.0", "info": { "title": "FlowGuard API v1", "version": "1.2.0", "description": "Query FlowGuard request logs and manage rules, actions, proxies, and IP lists for the authenticated team." }, "servers": [ { "url": "https:\/\/flowguard.network\/api\/v1" } ], "tags": [ { "name": "Logs", "description": "Endpoints for discovering and querying FlowGuard request logs." }, { "name": "Rules", "description": "Endpoints for discovering and managing FlowGuard request-matching rules." }, { "name": "Actions", "description": "Endpoints for managing the actions FlowGuard applies when rules match." }, { "name": "Servers", "description": "Endpoints for discovering the FlowGuard proxies available to rules." }, { "name": "IP Lists", "description": "Endpoints for discovering the IP lists available to rule conditions." } ], "security": [ { "ctp": [] }, { "openid": [] }, { "ctt": [] } ], "paths": { "\/logs\/fields": { "get": { "operationId": "logs.fields", "description": "List the fields that can be used in log filters, including each field's value type, supported operators, and fixed options. Use this endpoint before constructing a log query instead of relying on hard-coded field names.", "summary": "List log fields", "tags": [ "Logs" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "operators": { "type": "array", "items": { "type": "string" } }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "type", "operators", "options" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:logs:read" ] }, { "ctp": [ "flowguard:logs:read" ] }, { "ctt": [ "flowguard:logs:read" ] } ] } }, "\/rules\/capabilities": { "get": { "operationId": "rules.capabilities", "description": "Return the condition operators, match types, action results, server scope modes, and nesting limit supported by the current FlowGuard API. Use these capabilities to construct valid rule payloads.", "summary": "Show rule capabilities", "tags": [ "Rules" ], "responses": { "200": { "description": "The rule language and action capabilities supported by the current API.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "condition_operators": { "type": "array", "items": { "type": "object", "properties": { "value": { "$ref": "#\/components\/schemas\/RuleCondition" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "condition_types": { "type": "array", "items": { "type": "object", "properties": { "value": { "$ref": "#\/components\/schemas\/RuleType" }, "label": { "type": "string" }, "matches": { "type": "array", "items": { "$ref": "#\/components\/schemas\/RuleMatch" } }, "requires_key": { "type": "boolean" }, "additional_options": { "type": "array", "items": { "type": "string" } } }, "required": [ "value", "label", "matches", "requires_key", "additional_options" ] } }, "action_results": { "type": "array", "items": { "type": "object", "properties": { "value": { "$ref": "#\/components\/schemas\/ActionResult" }, "label": { "type": "string" }, "default_status_code": { "type": "integer" }, "default_message": { "type": "string" } }, "required": [ "value", "label", "default_status_code", "default_message" ] } }, "server_scope_modes": { "type": "array", "items": { "type": "object", "properties": { "value": { "$ref": "#\/components\/schemas\/RuleServerScopeMode" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "max_group_depth": { "type": "integer" } }, "required": [ "condition_operators", "condition_types", "action_results", "server_scope_modes", "max_group_depth" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:rules:read" ] }, { "ctp": [ "flowguard:rules:read" ] }, { "ctt": [ "flowguard:rules:read" ] } ] } }, "\/actions": { "get": { "operationId": "actions.index", "description": "List the authenticated team's reusable rule actions, newest first. Results can be searched by name and include the number of rules using each action.", "summary": "List actions", "tags": [ "Actions" ], "parameters": [ { "name": "query", "in": "query", "description": "Search results by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "edge protection" }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Array of `Action`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:actions:read" ] }, { "ctp": [ "flowguard:actions:read" ] }, { "ctt": [ "flowguard:actions:read" ] } ] }, "post": { "operationId": "actions.create", "description": "Create a reusable action for the authenticated team. The selected result determines which configuration fields are applicable; consult the rule capabilities endpoint for supported results and defaults.", "summary": "Create an action", "tags": [ "Actions" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveActionRequest" } } } }, "responses": { "201": { "description": "The action was created.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Action" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:actions:write" ] }, { "ctp": [ "flowguard:actions:write" ] }, { "ctt": [ "flowguard:actions:write" ] } ] } }, "\/servers": { "get": { "operationId": "servers.index", "description": "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.", "summary": "List servers", "tags": [ "Servers" ], "parameters": [ { "name": "query", "in": "query", "description": "Search results by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "edge protection" }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Array of `Server`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Server" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:servers:read" ] }, { "ctp": [ "flowguard:servers:read" ] }, { "ctt": [ "flowguard:servers:read" ] } ] }, "post": { "operationId": "servers.create", "description": "Create a FlowGuard proxy record for the authenticated team. Setup credentials remain available only in the web application.", "summary": "Create a server", "tags": [ "Servers" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveServerRequest" } } } }, "responses": { "201": { "description": "The server was created.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Server" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:servers:write" ] }, { "ctp": [ "flowguard:servers:write" ] }, { "ctt": [ "flowguard:servers:write" ] } ] } }, "\/ip-lists": { "get": { "operationId": "ip-lists.index", "description": "List team-owned and global IP lists that can be referenced by IP-list rule conditions. The response indicates whether a list supports confidence thresholds.", "summary": "List IP lists", "tags": [ "IP Lists" ], "parameters": [ { "name": "query", "in": "query", "description": "Search results by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "edge protection" }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `IPList`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/IPList" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:read" ] }, { "ctp": [ "flowguard:ip_lists:read" ] }, { "ctt": [ "flowguard:ip_lists:read" ] } ] }, "post": { "operationId": "ip-lists.create", "description": "Create an empty custom IP list for the authenticated team. Managed global lists cannot be created through this API.", "summary": "Create an IP list", "tags": [ "IP Lists" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveIPListRequest" } } } }, "responses": { "201": { "description": "The IP list was created.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IPList" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:write" ] }, { "ctp": [ "flowguard:ip_lists:write" ] }, { "ctt": [ "flowguard:ip_lists:write" ] } ] } }, "\/actions\/{action}": { "get": { "operationId": "actions.single", "description": "Show one reusable action belonging to the authenticated team, including its result configuration and the number of rules using it.", "summary": "Show an action", "tags": [ "Actions" ], "parameters": [ { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Action`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Action" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:actions:read" ] }, { "ctp": [ "flowguard:actions:read" ] }, { "ctt": [ "flowguard:actions:read" ] } ] }, "patch": { "operationId": "actions.update", "description": "Update an action belonging to the authenticated team. Omitted fields retain their current values. Changing the result replaces result-specific configuration with the supplied values and defaults for the new result.", "summary": "Update an action", "tags": [ "Actions" ], "parameters": [ { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveActionRequest" } } } }, "responses": { "200": { "description": "`Action`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Action" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:actions:write" ] }, { "ctp": [ "flowguard:actions:write" ] }, { "ctt": [ "flowguard:actions:write" ] } ] }, "delete": { "operationId": "actions.delete", "description": "Delete an action belonging to the authenticated team. Rules using the action remain in place but revert to doing nothing.", "summary": "Delete an action", "tags": [ "Actions" ], "parameters": [ { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The action was deleted and detached from its rules.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:actions:write" ] }, { "ctp": [ "flowguard:actions:write" ] }, { "ctt": [ "flowguard:actions:write" ] } ] } }, "\/ip-lists\/{ipList}\/entries": { "get": { "operationId": "ip-lists.entries.index", "description": "List entries in a team-owned or managed global IP list. Search by address, network, comment, or formatted entry ID.", "summary": "List IP-list entries", "tags": [ "IP Lists" ], "parameters": [ { "name": "ipList", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "description": "Search by IP address, CIDR, comment, or formatted entry ID.", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated set of `IPListEntry`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/IPListEntry" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:read" ] }, { "ctp": [ "flowguard:ip_lists:read" ] }, { "ctt": [ "flowguard:ip_lists:read" ] } ] }, "post": { "operationId": "ip-lists.entries.create", "description": "Add up to 1,000 entries to a custom IP list. Values are normalized, and duplicates in the request or list are skipped.", "summary": "Import IP-list entries", "tags": [ "IP Lists" ], "parameters": [ { "name": "ipList", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ImportIPListEntriesRequest" } } } }, "responses": { "200": { "description": "Every supplied entry already existed.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "201": { "description": "One or more IP-list entries were created.", "content": { "application\/json": { "schema": { "type": "string" } } } } }, "security": [ { "openid": [ "flowguard:ip_lists:write" ] }, { "ctp": [ "flowguard:ip_lists:write" ] }, { "ctt": [ "flowguard:ip_lists:write" ] } ] } }, "\/ip-lists\/{ipList}\/entries\/{entry}": { "get": { "operationId": "ip-lists.entries.single", "description": "Show one entry from a team-owned or managed global IP list available to the authenticated team.", "summary": "Show an IP-list entry", "tags": [ "IP Lists" ], "parameters": [ { "name": "ipList", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entry", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`IPListEntry`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IPListEntry" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:read" ] }, { "ctp": [ "flowguard:ip_lists:read" ] }, { "ctt": [ "flowguard:ip_lists:read" ] } ] }, "patch": { "operationId": "ip-lists.entries.update", "description": "Update an entry in a custom IP list belonging to the authenticated team. Omitted fields retain their current values.", "summary": "Update an IP-list entry", "tags": [ "IP Lists" ], "parameters": [ { "name": "ipList", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entry", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveIPListEntryRequest" } } } }, "responses": { "200": { "description": "`IPListEntry`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IPListEntry" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:write" ] }, { "ctp": [ "flowguard:ip_lists:write" ] }, { "ctt": [ "flowguard:ip_lists:write" ] } ] }, "delete": { "operationId": "ip-lists.entries.delete", "description": "Delete an entry from a custom IP list belonging to the authenticated team.", "summary": "Delete an IP-list entry", "tags": [ "IP Lists" ], "parameters": [ { "name": "ipList", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entry", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The IP-list entry was deleted.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:write" ] }, { "ctp": [ "flowguard:ip_lists:write" ] }, { "ctt": [ "flowguard:ip_lists:write" ] } ] } }, "\/ip-lists\/{ipList}": { "get": { "operationId": "ip-lists.single", "description": "Show one team-owned or managed global IP list available to the authenticated team.", "summary": "Show an IP list", "tags": [ "IP Lists" ], "parameters": [ { "name": "ipList", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`IPList`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IPList" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:read" ] }, { "ctp": [ "flowguard:ip_lists:read" ] }, { "ctt": [ "flowguard:ip_lists:read" ] } ] }, "patch": { "operationId": "ip-lists.update", "description": "Rename a custom IP list belonging to the authenticated team. Managed global lists are read-only.", "summary": "Update an IP list", "tags": [ "IP Lists" ], "parameters": [ { "name": "ipList", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveIPListRequest" } } } }, "responses": { "200": { "description": "`IPList`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IPList" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:write" ] }, { "ctp": [ "flowguard:ip_lists:write" ] }, { "ctt": [ "flowguard:ip_lists:write" ] } ] }, "delete": { "operationId": "ip-lists.delete", "description": "Delete a custom IP list belonging to the authenticated team. A list referenced by a rule or trusted-proxy configuration must be detached first.", "summary": "Delete an IP list", "tags": [ "IP Lists" ], "parameters": [ { "name": "ipList", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The IP list was deleted.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "409": { "description": "The IP list is still in use.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Detach the IP list before deleting it." ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:ip_lists:write" ] }, { "ctp": [ "flowguard:ip_lists:write" ] }, { "ctt": [ "flowguard:ip_lists:write" ] } ] } }, "\/logs\/by-stream\/{streamId}": { "get": { "operationId": "logs.by-stream", "description": "Return the newest retained request log with an exact, case-sensitive stream ID match.", "summary": "Retrieve a log by stream ID", "tags": [ "Logs" ], "parameters": [ { "name": "streamId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The matching request log.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "data": { "cursor": "eyJ0aW1lc3RhbXAiOjE3NzczNzQwMDAwMDAsImlkIjoic3ludGhldGljLWV2ZW50In0=", "timestamp": "2026-09-03T11:58:00Z", "fields": { "stream_id": "synthetic-stream-7f2a", "request.url.domain": "service.example.test", "client.ip": "192.0.2.44" } } } ], "properties": { "data": { "type": "object", "properties": { "cursor": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] }, "fields": { "type": "object", "additionalProperties": {} } }, "required": [ "cursor", "timestamp", "fields" ] } }, "required": [ "data" ] } } } }, "404": { "description": "No retained log has the supplied stream ID.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "No retained log was found for this stream ID." }, "code": { "type": "string", "const": "log_not_found" } }, "required": [ "message", "code" ] } } } }, "502": { "description": "The configured log provider could not complete the lookup.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The log provider could not complete the lookup." }, "code": { "type": "string", "const": "log_provider_error" } }, "required": [ "message", "code" ] } } } }, "409": { "description": "Request logging is not configured for the authenticated team.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Request logging is not configured for this team." }, "code": { "type": "string", "const": "logs_not_configured" } }, "required": [ "message", "code" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:logs:read" ] }, { "ctp": [ "flowguard:logs:read" ] }, { "ctt": [ "flowguard:logs:read" ] } ] } }, "\/logs\/query": { "post": { "operationId": "logs.query", "description": "Query request logs for the authenticated team within a time range. Results use cursor pagination and are ordered by timestamp and a stable event identifier. When continuing a query, send the returned cursor unchanged and keep the same time range, filters, and direction.", "summary": "Query request logs", "tags": [ "Logs" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/QueryLogsRequest" } } } }, "responses": { "200": { "description": "Matching request log events and cursor pagination metadata.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "data": [ { "cursor": "eyJ0aW1lc3RhbXAiOjE3NzczNzQwMDAwMDAsImlkIjoic3ludGhldGljLWV2ZW50In0=", "timestamp": "2026-09-03T11:58:00Z", "fields": { "request.method": "GET", "request.url.domain": "service.example.test", "client.ip": "192.0.2.44", "response.status": 403 } } ], "meta": { "next_cursor": null, "has_more": false, "from": "2026-09-02T12:00:00Z", "to": "2026-09-03T12:00:00Z", "direction": "desc", "limit": 100 } } ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "cursor": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] }, "fields": { "type": "object", "additionalProperties": {} } }, "required": [ "cursor", "timestamp", "fields" ] } }, "meta": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" }, "direction": { "type": "string" }, "limit": { "type": "integer" } }, "required": [ "next_cursor", "has_more", "from", "to", "direction", "limit" ] } }, "required": [ "data", "meta" ] } } } }, "502": { "description": "The configured log provider could not complete the query.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The log provider could not complete the query." }, "code": { "type": "string", "const": "log_provider_error" } }, "required": [ "message", "code" ] } } } }, "409": { "description": "Request logging is not configured for the authenticated team.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Request logging is not configured for this team." }, "code": { "type": "string", "const": "logs_not_configured" } }, "required": [ "message", "code" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:logs:read" ] }, { "ctp": [ "flowguard:logs:read" ] }, { "ctt": [ "flowguard:logs:read" ] } ] } }, "\/logs\/window": { "post": { "operationId": "logs.window", "description": "Return chronological context around a timestamp, stream ID, or opaque log cursor. Stream ID and cursor anchors are included even when they do not match the supplied filters; filters apply to surrounding events.", "summary": "Retrieve a log window", "tags": [ "Logs" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/LogWindowRequest" } } } }, "responses": { "200": { "description": "A chronological window of request logs and bidirectional cursor metadata.", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "data": [ { "cursor": "eyJ0aW1lc3RhbXAiOjE3NzczNzQwMDAwMDAsImlkIjoic3ludGhldGljLWV2ZW50In0=", "timestamp": "2026-09-03T11:58:00Z", "fields": { "stream_id": "synthetic-stream-7f2a", "request.url.domain": "service.example.test", "client.ip": "192.0.2.44" } } ], "meta": { "anchor": { "type": "timestamp", "cursor": "eyJ0aW1lc3RhbXAiOjE3NzczNzQwMDAwMDAsImlkIjoic3ludGhldGljLWV2ZW50In0=", "timestamp": "2026-09-03T11:58:00Z" }, "from": "2026-08-04T12:00:00Z", "to": "2026-09-03T12:00:00Z", "older_cursor": null, "newer_cursor": null, "has_older": false, "has_newer": false, "before": 50, "after": 50 } } ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "cursor": { "type": "string" }, "timestamp": { "type": [ "string", "null" ] }, "fields": { "type": "object", "additionalProperties": {} } }, "required": [ "cursor", "timestamp", "fields" ] } }, "meta": { "type": "object", "properties": { "anchor": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/LogWindowAnchorType" }, "cursor": { "type": [ "string", "null" ] }, "timestamp": { "type": "string" } }, "required": [ "type", "cursor", "timestamp" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "older_cursor": { "type": [ "string", "null" ] }, "newer_cursor": { "type": [ "string", "null" ] }, "has_older": { "type": "boolean" }, "has_newer": { "type": "boolean" }, "before": { "type": "integer" }, "after": { "type": "integer" } }, "required": [ "anchor", "from", "to", "older_cursor", "newer_cursor", "has_older", "has_newer", "before", "after" ] } }, "required": [ "data", "meta" ] } } } }, "502": { "description": "The configured log provider could not complete the query.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The log provider could not complete the query." }, "code": { "type": "string", "const": "log_provider_error" } }, "required": [ "message", "code" ] } } } }, "409": { "description": "Request logging is not configured for the authenticated team.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Request logging is not configured for this team." }, "code": { "type": "string", "const": "logs_not_configured" } }, "required": [ "message", "code" ] } } } }, "404": { "description": "The supplied stream ID or cursor does not identify a retained log.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The anchor does not identify a retained log." }, "code": { "type": "string", "const": "log_not_found" } }, "required": [ "message", "code" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:logs:read" ] }, { "ctp": [ "flowguard:logs:read" ] }, { "ctt": [ "flowguard:logs:read" ] } ] } }, "\/rules": { "get": { "operationId": "rules.index", "description": "List the authenticated team's rules in evaluation order. A lower position is evaluated first. Results can be searched by name and are paginated.", "summary": "List rules", "tags": [ "Rules" ], "parameters": [ { "name": "query", "in": "query", "description": "Search results by name.", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "example": "edge protection" }, { "name": "per_page", "in": "query", "description": "Number of results per page.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number to return.", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Array of `Rule`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Rule" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:rules:read" ] }, { "ctp": [ "flowguard:rules:read" ] }, { "ctt": [ "flowguard:rules:read" ] } ] }, "post": { "operationId": "rules.create", "description": "Create a rule for the authenticated team. The optional action must belong to the same team. A supplied zero-based position inserts the rule at that point and shifts later rules down; when omitted, the rule is appended.", "summary": "Create a rule", "tags": [ "Rules" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveRuleRequest" } } } }, "responses": { "201": { "description": "The rule was created.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Rule" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:rules:write" ] }, { "ctp": [ "flowguard:rules:write" ] }, { "ctt": [ "flowguard:rules:write" ] } ] } }, "\/rules\/{rule}": { "get": { "operationId": "rules.single", "description": "Show one rule belonging to the authenticated team, including its conditions, action, server scope, and evaluation position.", "summary": "Show a rule", "tags": [ "Rules" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Rule`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Rule" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:rules:read" ] }, { "ctp": [ "flowguard:rules:read" ] }, { "ctt": [ "flowguard:rules:read" ] } ] }, "patch": { "operationId": "rules.update", "description": "Update a rule belonging to the authenticated team. Omitted top-level fields retain their current values. Set action_id to null to detach the action; changing position reorders the team's rules.", "summary": "Update a rule", "tags": [ "Rules" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveRuleRequest" } } } }, "responses": { "200": { "description": "`Rule`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Rule" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:rules:write" ] }, { "ctp": [ "flowguard:rules:write" ] }, { "ctt": [ "flowguard:rules:write" ] } ] }, "delete": { "operationId": "rules.delete", "description": "Delete a rule belonging to the authenticated team and close the gap in the remaining evaluation positions.", "summary": "Delete a rule", "tags": [ "Rules" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The rule was deleted.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:rules:write" ] }, { "ctp": [ "flowguard:rules:write" ] }, { "ctt": [ "flowguard:rules:write" ] } ] } }, "\/rules\/{rule}\/disable": { "post": { "operationId": "rules.disable", "description": "Remove the action assigned to a rule belonging to the authenticated team. The rule and its conditions remain available for later use.", "summary": "Disable a rule", "tags": [ "Rules" ], "parameters": [ { "name": "rule", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Rule`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Rule" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:rules:write" ] }, { "ctp": [ "flowguard:rules:write" ] }, { "ctt": [ "flowguard:rules:write" ] } ] } }, "\/servers\/{server}": { "get": { "operationId": "servers.single", "description": "Show one FlowGuard proxy belonging to the authenticated team, including its desired configuration, health, and capabilities. Credentials are never exposed.", "summary": "Show a server", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`Server`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Server" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:servers:read" ] }, { "ctp": [ "flowguard:servers:read" ] }, { "ctt": [ "flowguard:servers:read" ] } ] }, "patch": { "operationId": "servers.update", "description": "Update a FlowGuard proxy belonging to the authenticated team. Omitted fields retain their current values, and null clears nullable path and hostname fields.", "summary": "Update a server", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SaveServerRequest" } } } }, "responses": { "200": { "description": "`Server`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/Server" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [ { "openid": [ "flowguard:servers:write" ] }, { "ctp": [ "flowguard:servers:write" ] }, { "ctt": [ "flowguard:servers:write" ] } ] }, "delete": { "operationId": "servers.delete", "description": "Delete a FlowGuard proxy record belonging to the authenticated team. The proxy installation must be removed separately from its host.", "summary": "Delete a server", "tags": [ "Servers" ], "parameters": [ { "name": "server", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The server was deleted.", "content": { "application\/json": { "schema": { "type": "string" } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } }, "security": [ { "openid": [ "flowguard:servers:write" ] }, { "ctp": [ "flowguard:servers:write" ] }, { "ctt": [ "flowguard:servers:write" ] } ] } } }, "components": { "securitySchemes": { "ctp": { "type": "http", "description": "Chief Tools personal access token.", "scheme": "bearer", "bearerFormat": "ctp_*" }, "openid": { "type": "openIdConnect", "openIdConnectUrl": "https:\/\/account.chief.app\/.well-known\/openid-configuration" }, "ctt": { "type": "http", "description": "Chief Tools team access token.", "scheme": "bearer", "bearerFormat": "ctt_*" } }, "schemas": { "Action": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted action ID.", "examples": [ "action_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "Block synthetic scanners" ] }, "result": { "description": "Action result applied to a matching request.", "$ref": "#\/components\/schemas\/ActionResult" }, "status_code": { "type": [ "integer", "null" ], "description": "HTTP status returned by results that produce a response." }, "message": { "type": [ "string", "null" ], "description": "Response message returned by results that produce a response." }, "window_seconds": { "type": [ "integer", "null" ], "description": "Rate-limit window in seconds, or null for other results." }, "requests_per_window": { "type": [ "integer", "null" ], "description": "Requests allowed per rate-limit window, or null for other results." }, "rules_count": { "type": "integer", "description": "Number of rules currently using this action." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "name", "result", "status_code", "message", "window_seconds", "requests_per_window", "created_at", "updated_at" ], "title": "Action" }, "ActionResult": { "type": "string", "x-extensible-enum": [ "allow", "block", "challenge", "rate_limit", "log" ], "title": "ActionResult" }, "IPList": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted IP list ID accepted by IP-list rule conditions.", "examples": [ "iplist_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "Synthetic threat feed" ] }, "is_global": { "type": "boolean", "description": "Whether the list is managed globally instead of by the authenticated team." }, "supports_confidence": { "type": "boolean", "description": "Whether IP-list rule matches may specify a confidence threshold." }, "entries_count": { "type": "integer", "description": "Number of entries in the list when requested by the endpoint." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "name", "is_global", "supports_confidence", "created_at", "updated_at" ], "title": "IPList" }, "IPListEntry": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted IP-list entry ID.", "examples": [ "iplist_entry_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "content": { "type": "string", "description": "Normalized IPv4, IPv6, or CIDR value." }, "type": { "description": "Entry address type.", "$ref": "#\/components\/schemas\/IPListEntryType" }, "comment": { "type": [ "string", "null" ], "description": "Optional note associated with the entry." }, "confidence": { "type": [ "integer", "null" ], "description": "Confidence assigned by a managed list, or null for custom lists." }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "content", "type", "comment", "confidence", "created_at", "updated_at" ], "title": "IPListEntry" }, "IPListEntryType": { "type": "integer", "x-extensible-enum": [ 1, 2, 3, 4 ], "title": "IPListEntryType" }, "ImportIPListEntriesRequest": { "type": "object", "properties": { "entries": { "type": "array", "description": "Entries to normalize and add to the custom IP list.", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "IPv4, IPv6, or CIDR value.", "examples": [ "192.0.2.0\/24" ], "maxLength": 255 }, "comment": { "type": [ "string", "null" ], "description": "Optional note associated with the entry.", "maxLength": 255 } }, "required": [ "content", "comment" ] }, "minItems": 1, "maxItems": 1000 } }, "required": [ "entries" ], "title": "ImportIPListEntriesRequest" }, "LogWindowAnchorType": { "type": "string", "x-extensible-enum": [ "timestamp", "stream_id", "cursor" ], "title": "LogWindowAnchorType" }, "LogWindowRequest": { "type": "object", "properties": { "anchor": { "type": "object", "description": "Anchor used to center the returned log window.", "properties": { "type": { "type": "string", "description": "Anchor kind: an ISO 8601 timestamp, a stream ID, or an opaque log cursor.", "enum": [ "timestamp", "stream_id", "cursor" ] }, "value": { "type": "string", "description": "Anchor value matching the selected anchor type.", "maxLength": 2048 } }, "required": [ "type", "value" ] }, "before": { "type": "integer", "description": "Number of matching events to retrieve before the anchor.", "minimum": 0, "maximum": 200 }, "after": { "type": "integer", "description": "Number of matching events to retrieve after the anchor.", "minimum": 0, "maximum": 200 }, "filters": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "string", "enum": [ "stream_id", "cloudflare.ray_id", "rule.id", "rule.name", "rule.result", "rule.action.id", "rule.action.name", "challenge.outcome", "challenge.reason", "challenge.scope", "challenge.rule.id", "challenge.rule.name", "challenge.action.id", "challenge.action.name", "request.method", "request.url.scheme", "request.url.domain", "request.url.registerable_domain", "request.url.path", "request.url.full", "request.headers.user-agent", "request.headers.referer", "request.tls.version", "request.fingerprint.ja4", "request.http_version", "response.status", "response.resource.type", "response.resource.static_candidate", "response.resource.source", "response.resource.mime", "response.resource.extension", "response.headers.content-type", "response.headers.location", "client.ip", "client.as.num", "client.as.name", "client.as.domain", "client.country", "proxy.ip", "proxy.as.num", "proxy.as.name", "proxy.as.domain", "proxy.country", "host.id", "host.name" ] }, "operator": { "type": "string", "enum": [ "equals", "not-equals", "contains", "not-contains", "starts-with", "ends-with" ] }, "value": { "type": "string" } }, "required": [ "column", "operator", "value" ] }, "minItems": 1, "maxItems": 50 } }, "required": [ "operator", "conditions" ] }, "maxItems": 20 } }, "required": [ "operator", "groups" ] } }, "required": [ "anchor", "before", "after", "filters" ], "title": "LogWindowRequest" }, "QueryLogsRequest": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Inclusive beginning of the query range. Defaults to 24 hours before `to`.", "examples": [ "2026-09-02T12:00:00Z" ] }, "to": { "type": "string", "format": "date-time", "description": "Exclusive end of the query range. Defaults to the current time.", "examples": [ "2026-09-03T12:00:00Z" ] }, "direction": { "type": "string", "description": "Sort order for matching events.", "enum": [ "asc", "desc" ], "default": "desc", "examples": [ "desc" ] }, "limit": { "type": "integer", "description": "Maximum number of events to return.", "default": 100, "minimum": 1, "maximum": 200 }, "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor returned as `meta.next_cursor` by the previous page. Keep the time range, filters, and direction unchanged when continuing a query.", "examples": [ "eyJ0aW1lc3RhbXAiOjE3NzczNzQwMDAwMDAsImlkIjoic3ludGhldGljLWV2ZW50In0=" ], "maxLength": 2048 }, "filters": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "groups": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "string", "enum": [ "stream_id", "cloudflare.ray_id", "rule.id", "rule.name", "rule.result", "rule.action.id", "rule.action.name", "challenge.outcome", "challenge.reason", "challenge.scope", "challenge.rule.id", "challenge.rule.name", "challenge.action.id", "challenge.action.name", "request.method", "request.url.scheme", "request.url.domain", "request.url.registerable_domain", "request.url.path", "request.url.full", "request.headers.user-agent", "request.headers.referer", "request.tls.version", "request.fingerprint.ja4", "request.http_version", "response.status", "response.resource.type", "response.resource.static_candidate", "response.resource.source", "response.resource.mime", "response.resource.extension", "response.headers.content-type", "response.headers.location", "client.ip", "client.as.num", "client.as.name", "client.as.domain", "client.country", "proxy.ip", "proxy.as.num", "proxy.as.name", "proxy.as.domain", "proxy.country", "host.id", "host.name" ] }, "operator": { "type": "string", "enum": [ "equals", "not-equals", "contains", "not-contains", "starts-with", "ends-with" ] }, "value": { "type": "string" } }, "required": [ "column", "operator", "value" ] }, "minItems": 1, "maxItems": 50 } }, "required": [ "operator", "conditions" ] }, "maxItems": 20 } }, "required": [ "operator", "groups" ] } }, "required": [ "from", "to", "direction", "limit", "filters" ], "title": "QueryLogsRequest" }, "Rule": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted rule ID.", "examples": [ "rule_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "Protect synthetic service" ] }, "position": { "type": "integer", "description": "Zero-based evaluation position. Lower positions are evaluated first." }, "action_id": { "type": [ "string", "null" ], "description": "Formatted action ID, or null when the rule has no action." }, "conditions": { "type": "object", "description": "Normalized recursive condition group evaluated by the rule.", "properties": { "operator": { "$ref": "#\/components\/schemas\/RuleCondition" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/RuleType" }, "match": { "$ref": "#\/components\/schemas\/RuleMatch" }, "key": { "type": "string" }, "value": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "integer" }, "case_insensitive": { "type": "boolean" }, "raw_match": { "type": "boolean" } }, "required": [ "type", "match" ] } }, "groups": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "operator" ] }, "server_scope": { "type": "object", "description": "Server scope controlling which proxies evaluate the rule.", "properties": { "mode": { "$ref": "#\/components\/schemas\/RuleServerScopeMode" }, "server_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "server_ids" ] }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "name", "position", "action_id", "conditions", "server_scope", "created_at", "updated_at" ], "title": "Rule" }, "RuleCondition": { "type": "string", "x-extensible-enum": [ "AND", "OR", "NAND", "NOR" ], "title": "RuleCondition" }, "RuleMatch": { "type": "string", "x-extensible-enum": [ "equals", "not-equals", "contains", "not-contains", "starts-with", "not-starts-with", "ends-with", "not-ends-with", "in", "not-in", "regex", "not-regex", "exists", "missing" ], "title": "RuleMatch" }, "RuleServerScopeMode": { "type": "string", "x-extensible-enum": [ "all", "include", "exclude" ], "title": "RuleServerScopeMode" }, "RuleType": { "type": "string", "x-extensible-enum": [ "domain", "registerable-domain", "path", "method", "header", "query-param", "cookie", "user-agent", "ip", "proxy-ip", "country", "continent", "asn", "proxy-asn", "as-name", "as-domain", "iplist", "proxy-iplist", "fingerprint-ja4" ], "title": "RuleType" }, "SaveActionRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable action name.", "examples": [ "Block synthetic scanners" ], "maxLength": 255 }, "result": { "type": "string", "description": "Result applied when a rule using this action matches.", "enum": [ "allow", "block", "challenge", "rate_limit", "log" ] }, "status_code": { "type": [ "integer", "null" ], "description": "HTTP status returned by results that produce a response.", "minimum": 100, "maximum": 599 }, "message": { "type": [ "string", "null" ], "description": "Response message returned by results that produce a response.", "maxLength": 255 }, "window_seconds": { "type": [ "integer", "null" ], "description": "Rate-limit window in seconds. Required when `result` is `rate_limit`.", "minimum": 1, "maximum": 86400 }, "requests_per_window": { "type": [ "integer", "null" ], "description": "Requests allowed during the rate-limit window. Required when `result` is `rate_limit`.", "minimum": 1 } }, "required": [ "name", "result" ], "title": "SaveActionRequest" }, "SaveIPListEntryRequest": { "type": "object", "properties": { "content": { "type": "string", "description": "IPv4, IPv6, or CIDR value.", "examples": [ "198.51.100.24" ], "maxLength": 255 }, "comment": { "type": [ "string", "null" ], "description": "Optional note associated with the entry.", "maxLength": 255 } }, "required": [ "content", "comment" ], "title": "SaveIPListEntryRequest" }, "SaveIPListRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable IP-list name.", "examples": [ "Synthetic blocked networks" ], "maxLength": 255 } }, "required": [ "name" ], "title": "SaveIPListRequest" }, "SaveRuleRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable rule name.", "examples": [ "Protect synthetic service" ], "maxLength": 255 }, "action_id": { "type": [ "string", "null" ], "description": "Formatted ID of an action owned by the authenticated team. Send null for a match-only rule." }, "conditions": { "type": "object", "description": "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.", "examples": [ { "operator": "AND", "matches": [ { "type": "domain", "match": "equals", "value": "service.example.test" } ], "groups": [] } ], "properties": { "operator": { "$ref": "#\/components\/schemas\/RuleCondition" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#\/components\/schemas\/RuleType" }, "match": { "$ref": "#\/components\/schemas\/RuleMatch" }, "key": { "type": "string" }, "value": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "integer" }, "case_insensitive": { "type": "boolean" }, "raw_match": { "type": "boolean" } }, "required": [ "type", "match" ] } }, "groups": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "operator", "matches", "groups" ] }, "server_scope": { "type": "object", "description": "Server scope controlling which proxies evaluate the rule.", "properties": { "mode": { "type": "string", "description": "Use `all` for every team proxy, `include` for only the listed proxies, or `exclude` for every proxy except those listed.", "enum": [ "all", "include", "exclude" ] }, "server_ids": { "type": "array", "description": "Formatted server IDs. Must be empty when mode is `all`.", "items": { "type": "string" }, "uniqueItems": true } }, "required": [ "mode", "server_ids" ] }, "position": { "type": "integer", "description": "Zero-based evaluation position. Omit when creating to append the rule; omit when updating to retain its current position.", "examples": [ 0 ], "minimum": 0 } }, "required": [ "name", "conditions", "server_scope" ], "title": "SaveRuleRequest" }, "SaveServerRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable proxy name.", "examples": [ "Synthetic edge proxy" ], "maxLength": 255 }, "default_hostname": { "type": [ "string", "null" ], "description": "Default TLS hostname, or null to reject connections without a matching certificate.", "maxLength": 255 }, "cert_path": { "type": [ "string", "null" ], "description": "Absolute path containing combined certificate files.", "maxLength": 255 }, "acme_path": { "type": [ "string", "null" ], "description": "Absolute path to a Traefik ACME file.", "maxLength": 255 }, "nginx_config_path": { "type": [ "string", "null" ], "description": "Absolute path to an NGINX configuration file.", "maxLength": 255 }, "allow_unattended_upgrades": { "type": "boolean", "description": "Allow upgrades initiated by FlowGuard." }, "protocols": { "type": "object", "description": "Protocol configuration applied by the proxy.", "properties": { "http1": { "type": "boolean" }, "http2": { "type": "boolean" }, "http3": { "type": "boolean" }, "advertise_http3": { "type": "boolean" } }, "required": [ "http1", "http2", "http3", "advertise_http3" ] }, "fail2ban_enabled": { "type": "boolean", "description": "Enable the host-level Fail2Ban integration." } }, "required": [ "name" ], "title": "SaveServerRequest" }, "Server": { "type": "object", "properties": { "id": { "type": "string", "description": "Formatted server ID accepted by rule server scopes.", "examples": [ "server_01j8q8zk2f4m6n7p9r1s3t5v7x" ] }, "name": { "type": "string", "examples": [ "Synthetic edge" ] }, "version": { "type": [ "string", "null" ], "description": "Currently reported FlowGuard proxy version." }, "heartbeat_status": { "type": [ "string", "null" ], "description": "Health status calculated from the proxy's latest heartbeat." }, "config_up_to_date": { "type": "boolean", "description": "Whether the proxy has loaded the latest desired configuration." }, "default_hostname": { "type": [ "string", "null" ], "description": "Default TLS hostname, or null when unmatched connections are rejected." }, "cert_path": { "type": [ "string", "null" ], "description": "Absolute path containing combined certificate files." }, "acme_path": { "type": [ "string", "null" ], "description": "Absolute path to a Traefik ACME file." }, "nginx_config_path": { "type": [ "string", "null" ], "description": "Absolute path to an NGINX configuration file." }, "allow_unattended_upgrades": { "type": "boolean", "description": "Whether FlowGuard may initiate proxy upgrades." }, "protocols": { "type": "object", "description": "HTTP protocols served by the proxy.", "properties": { "http1": { "type": "boolean" }, "http2": { "type": "boolean" }, "http3": { "type": "boolean" }, "advertise_http3": { "type": "boolean" } }, "required": [ "http1", "http2", "http3", "advertise_http3" ] }, "fail2ban_enabled": { "type": "boolean", "description": "Whether the host-level Fail2Ban integration is enabled." }, "capabilities": { "type": "object", "description": "Rule features supported by the installed proxy version.", "properties": { "server_config": { "type": [ "boolean", "null" ], "description": "Whether the proxy supports remote configuration." }, "challenge_actions": { "type": "boolean", "description": "Whether the proxy supports challenge actions." }, "proxy_matchers": { "type": "boolean", "description": "Whether the proxy supports proxy-aware rule matchers." }, "acme_path": { "type": "boolean", "description": "Whether the proxy supports Traefik ACME paths." }, "upstream_client_ip_config": { "type": "boolean", "description": "Whether the proxy supports upstream client-IP configuration." }, "fail2ban": { "type": "boolean", "description": "Whether the proxy supports the Fail2Ban integration." }, "remote_upgrade": { "type": "boolean", "description": "Whether FlowGuard can upgrade the proxy remotely." } }, "required": [ "server_config", "challenge_actions", "proxy_matchers", "acme_path", "upstream_client_ip_config", "fail2ban", "remote_upgrade" ] }, "created_at": { "type": "string", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "description": "ISO 8601 last-update timestamp." } }, "required": [ "id", "name", "version", "heartbeat_status", "config_up_to_date", "default_hostname", "cert_path", "acme_path", "nginx_config_path", "allow_unattended_upgrades", "protocols", "fail2ban_enabled", "capabilities", "created_at", "updated_at" ], "title": "Server" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }