Перейти к основному содержимому
API docs by Redocly

qf Control Plane API (0.25.6)

Download OpenAPI specification:Download

REST API for the qf host-based firewall control plane.

Authentication: Most endpoints require either a JWT cookie (qf_token, set by POST /auth/login) or an Authorization: Bearer <token> header (JWT or opaque API token).

Tenant: Protected endpoints require the X-Tenant-ID header (UUID of the tenant).

Auth

Authentication and session management

Health check

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Application version

Responses

Response samples

Content type
application/json
{
  • "version": "string"
}

Prometheus metrics

Responses

JWKS — public keys for operator access-token verification

RS256 public key set. Operator access tokens are RSA-signed by the CP; verifiers (the CP itself and the analytics service) check signatures with this key without holding the signing key. Served only when a signing key is configured.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Enrollment CA certificate

Served only when the CP CA is configured.

Responses

SHA256 fingerprint of the enrollment CA

Hex digest of the CA certificate DER; transport out-of-band before using it as a pin.

Responses

Log in with email and password

Request Body schema: application/json
required
username
required
string
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Clear session cookies

Responses

Refresh access token using refresh cookie

Responses

Get current user identity

Authorizations:
cookieAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "role": "string",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "access_ttl_seconds": 0
}

Change the current local user's password

JWT authentication only; OIDC accounts cannot change a password here.

Authorizations:
cookieAuthbearerAuth
Request Body schema: application/json
required
current_password
required
string <password>
new_password
required
string <password> [ 8 .. 72 ] characters

Responses

Request samples

Content type
application/json
{
  • "current_password": "pa$$word",
  • "new_password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Check if OIDC login is enabled

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Initiate OIDC login flow (redirect to provider)

Responses

OIDC callback — exchange code for tokens

query Parameters
code
string
state
string

Responses

Build and runtime information for this CP replica (Admin only)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "git_sha": "string",
  • "git_branch": "string",
  • "build_time": "string",
  • "go_version": "string",
  • "hostname": "string",
  • "started_at": "2019-08-24T14:15:22Z",
  • "uptime_seconds": 0,
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

OpenAPI 3.0 spec (this file)

Responses

Swagger UI

Responses

Hosts

Managed firewall hosts

List hosts (cursor-paginated)

Authorizations:
cookieAuthbearerAuth
query Parameters
changed_since
string <date-time>

Reconnect-backfill delta cursor (UI live-sync). When present, the endpoint returns ONLY rows changed at or after changed_since - OVERLAP (a small server-applied safety window; client dedups by id), tenant-scoped exactly as the full list. Omit for the normal full-list response (unchanged). Format is RFC3339 with nanosecond precision (RFC3339Nano) so same-second bulk-enroll ties are preserved. For hosts, archived (soft-deleted) rows are surfaced as tombstones (archived_at set) so clients reconcile deletes. For tokens the filter is insert-only (bootstrap_tokens key on created_at).

limit
integer <= 10000
Default: 500
before
string <date-time>

Cursor — return hosts with created_at strictly before this RFC3339 timestamp (newest first).

cap
string
Enum: "32" "2048" "other"

VIZ-02 rule-cap drill-down filter — return only hosts whose resolved rule-cap tier equals this value. The resolved cap is metrics.rules_cap, falling back to capabilities.ruleCap; a host with no resolvable used+cap is excluded when this filter is set.

rules_min
integer

VIZ-02 drill-down filter — only hosts whose metrics.rules_used is ≥ this value (inclusive).

rules_max
integer

VIZ-02 drill-down filter — only hosts whose metrics.rules_used is ≤ this value (inclusive).

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a host

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
hostname
required
string
object
status
string
Default: "enrolling"

Responses

Request samples

Content type
application/json
{
  • "hostname": "string",
  • "labels": {
    },
  • "status": "enrolling"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "hostname": "string",
  • "labels": {
    },
  • "effective_labels": {
    },
  • "status": "enrolling",
  • "current_generation": 0,
  • "desired_generation": 0,
  • "last_confirmed_generation": 0,
  • "last_confirmed_at": "2019-08-24T14:15:22Z",
  • "config_version": 0,
  • "flow_events_enabled": true,
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "agent_version": "string",
  • "kernel_version": "string",
  • "last_seen_ip": "string",
  • "interfaces": [
    ],
  • "capabilities": { },
  • "isolation": {
    },
  • "metrics": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Rule-cap cohort distribution (tenant-scoped)

VIZ-02 fleet rule-cap pressure, aggregated server-side so the dashboard widget does not fetch the whole fleet. Hosts are grouped by resolved rule-cap tier (2048 bpf_loop / other), then bucketed into utilization cohorts (over/saturated/near/mid/low). Scoped to the caller's tenant.

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "tiers": [
    ],
  • "no_metrics": 0
}

Build a nested host tree from effective-label keys

Authorizations:
cookieAuthbearerAuth
query Parameters
keys
required
Array of strings [ 1 .. 5 ] items unique
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List hosts under an effective-label grouping path

Authorizations:
cookieAuthbearerAuth
query Parameters
keys
required
Array of strings [ 1 .. 5 ] items unique
path
Array of strings <= 5 items
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List distinct effective-label keys

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • "string"
]

List distinct effective values for a label key

Authorizations:
cookieAuthbearerAuth
query Parameters
key
required
string
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • "string"
]

List archived hosts (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a host by ID

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "hostname": "string",
  • "labels": {
    },
  • "effective_labels": {
    },
  • "status": "enrolling",
  • "current_generation": 0,
  • "desired_generation": 0,
  • "last_confirmed_generation": 0,
  • "last_confirmed_at": "2019-08-24T14:15:22Z",
  • "config_version": 0,
  • "flow_events_enabled": true,
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "agent_version": "string",
  • "kernel_version": "string",
  • "last_seen_ip": "string",
  • "interfaces": [
    ],
  • "capabilities": { },
  • "isolation": {
    },
  • "metrics": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Update host labels, status, or flow_events_enabled

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
object
status
string
flow_events_enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "labels": {
    },
  • "status": "string",
  • "flow_events_enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "hostname": "string",
  • "labels": {
    },
  • "effective_labels": {
    },
  • "status": "enrolling",
  • "current_generation": 0,
  • "desired_generation": 0,
  • "last_confirmed_generation": 0,
  • "last_confirmed_at": "2019-08-24T14:15:22Z",
  • "config_version": 0,
  • "flow_events_enabled": true,
  • "last_heartbeat_at": "2019-08-24T14:15:22Z",
  • "agent_version": "string",
  • "kernel_version": "string",
  • "last_seen_ip": "string",
  • "interfaces": [
    ],
  • "capabilities": { },
  • "isolation": {
    },
  • "metrics": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Archive a host, revoke its certificates, and disconnect its agent

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Read desired and applied isolation state

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "supported": true,
  • "revision": 7,
  • "desired": {
    },
  • "applied": {
    },
  • "status": "applied",
  • "target_generation": 18,
  • "error": null,
  • "requested_at": "2026-08-30T15:59:58Z"
}

Apply or replace host isolation

Idempotent by canonical desired representation. A new target or retry of a failed target returns 202. A request equal to an already pending/applied target returns 200 without a generation bump. Only admin and editor may call this operation.

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
mode
required
string
Enum: "full" "partial"
Array of objects (IsolationException)

Must be absent or empty for full mode and contain at least one item for partial mode. Exact duplicates are normalized. Each item permits the initiated flow and only its conntrack-confirmed response.

Responses

Request samples

Content type
application/json
{
  • "mode": "full",
  • "exceptions": [
    ]
}

Response samples

Content type
application/json
{
  • "supported": true,
  • "revision": 0,
  • "desired": {
    },
  • "applied": {
    },
  • "status": "pending",
  • "target_generation": 0,
  • "error": "string",
  • "requested_at": "2019-08-24T14:15:22Z"
}

Restore ordinary host networking

Idempotent. A new restore target or retry returns 202. If desired and applied state are already none, returns 200 without a generation bump. Only admin and editor may call this operation.

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "supported": true,
  • "revision": 0,
  • "desired": {
    },
  • "applied": {
    },
  • "status": "pending",
  • "target_generation": 0,
  • "error": "string",
  • "requested_at": "2019-08-24T14:15:22Z"
}

List host groups the host belongs to

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the effective compiled ruleset for a host

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "host_id": "eb4e20fc-2b4a-4d0c-811f-48abcf12b89b",
  • "default_ingress": "allow",
  • "default_egress": "allow",
  • "rules": [
    ]
}

Re-apply the current policy bundle to a host

Bumps desired_generation and re-pushes the host's current bundle, overwriting any manual datapath drift. Requires admin or editor.

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Restore an archived host (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Permanently purge an archived host after the retention window (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

List applied host-label config versions

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revert host labels to an applied version (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
v
required
integer >= 1
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

List pending host-label drafts

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stage a host-label draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Discard a host-label draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Preview the impact of a host-label draft without applying it

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "blast": {
    },
  • "traffic": [
    ],
  • "window": {
    }
}

Apply a host-label draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

HostGroups

Named host groups with shared labels

List host groups

Authorizations:
cookieAuthbearerAuth
query Parameters
changed_since
string <date-time>

Reconnect-backfill delta cursor (UI live-sync). When present, the endpoint returns ONLY rows changed at or after changed_since - OVERLAP (a small server-applied safety window; client dedups by id), tenant-scoped exactly as the full list. Omit for the normal full-list response (unchanged). Format is RFC3339 with nanosecond precision (RFC3339Nano) so same-second bulk-enroll ties are preserved. For hosts, archived (soft-deleted) rows are surfaced as tombstones (archived_at set) so clients reconcile deletes. For tokens the filter is insert-only (bootstrap_tokens key on created_at).

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a host group

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
name
required
string
object
priority
integer
Default: 100

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "labels": {
    },
  • "priority": 100
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "labels": {
    },
  • "priority": 0,
  • "member_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

List archived host groups (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a host group

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "labels": {
    },
  • "priority": 0,
  • "member_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Update a host group

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
name
string
object
priority
integer

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "labels": {
    },
  • "priority": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "labels": {
    },
  • "priority": 0,
  • "member_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Archive a host group

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

List hosts in a group

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a host to a group

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
host_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "host_id": "eb4e20fc-2b4a-4d0c-811f-48abcf12b89b"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Remove a host from a group

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
host_id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Restore an archived host group (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Permanently purge an archived host group (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

List applied host-group config versions

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revert a host group to an applied version (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
v
required
integer >= 1
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

List pending host-group drafts

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stage a host-group draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Discard a host-group draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Preview the impact of a host-group draft without applying it

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "blast": {
    },
  • "traffic": [
    ],
  • "window": {
    }
}

Apply a host-group draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Events

Log events, flow events, and counters per host

List system events for a host (datapath_drift, host_unreachable, …)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
query Parameters
limit
integer <= 10000
Default: 500
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List log events for a host

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
query Parameters
start
string <date-time>
end
string <date-time>
limit
integer <= 10000
Default: 500
rule_id
string <uuid>
action
string
Enum: "allow" "deny" "log"
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

SSE live tail of log events

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Last-Event-ID
string

Resume from this RFC3339Nano timestamp

Responses

List flow events for a host

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
query Parameters
start
string <date-time>
end
string <date-time>
limit
integer <= 10000
Default: 500
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Aggregate flow events for a host

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
query Parameters
group_by
string
Default: "by-dst"
Enum: "by-dst" "by-proto" "by-src-dst"
from
string <date-time>
to
string <date-time>
limit
integer <= 10000
Default: 500
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "group_by": "by-dst",
  • "window": {
    },
  • "rows": [
    ]
}

List counter snapshots for a host

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
query Parameters
start
string <date-time>
end
string <date-time>
limit
integer <= 10000
Default: 500
rule_id
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Latest counter snapshot per rule for a host

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Verdicts log-event aggregate (top denying rules/hosts, deny timeline)

Tenant-scoped rollup over the partitioned log_events table. group_by selects one closed preset (by-rule / by-host / timeline) — the string only SELECTS a static named query and is NEVER interpolated into SQL; an unknown non-empty value → 400. by-rule and timeline are host-scoped (host_id required); by-host aggregates top denying hosts across the whole tenant. The [from,to) window defaults to 24h and is capped 7d server-side so the scan stays partition-pruned. Read tier.

Authorizations:
cookieAuthbearerAuth
query Parameters
group_by
string
Enum: "by-rule" "by-host" "timeline"

Aggregate preset; omitted = by-rule. Unknown value → 400.

host_id
string <uuid>

Required for by-rule/timeline; ignored for by-host.

from
string <date-time>

Inclusive lower bound on created_at (RFC3339); default now-24h.

to
string <date-time>

Exclusive upper bound on created_at (RFC3339); default now.

limit
integer

Max rows for by-rule/by-host (default 500, capped 10000). Ignored by timeline.

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "group_by": "string",
  • "window": {
    },
  • "rows": [
    ]
}

Policies

Firewall policies and rules

List policies

Authorizations:
cookieAuthbearerAuth
query Parameters
changed_since
string <date-time>

Reconnect-backfill delta cursor (UI live-sync). When present, the endpoint returns ONLY rows changed at or after changed_since - OVERLAP (a small server-applied safety window; client dedups by id), tenant-scoped exactly as the full list. Omit for the normal full-list response (unchanged). Format is RFC3339 with nanosecond precision (RFC3339Nano) so same-second bulk-enroll ties are preserved. For hosts, archived (soft-deleted) rows are surfaced as tombstones (archived_at set) so clients reconcile deletes. For tokens the filter is insert-only (bootstrap_tokens key on created_at).

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a policy

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
name
required
string
description
string
priority
integer
Default: 0
selector
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "priority": 0,
  • "selector": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "priority": 0,
  • "selector": { },
  • "interface_names": [
    ],
  • "confirm_match_all": true,
  • "current_version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

List archived policies (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Policy coverage graph (bucket-aggregated)

Returns a bucket-aggregated view of which hosts each policy currently reaches, so the node count is bounded by policy×bucket instead of policy×host. Every edge carries a matched_hosts coverage count and every bucket a total_hosts denominator, both computed over the same active-host set (revoked and enrolling hosts are excluded), so matched_hosts is always less than or equal to total_hosts. The group_by parameter selects the bucket dimension.

Authorizations:
cookieAuthbearerAuth
query Parameters
group_by
string
Default: "hostgroup"
Example: group_by=label:env

Bucket dimension. hostgroup (default) buckets by host group — a host that belongs to several groups counts in each of them, and active hosts in no group fall into a synthetic (ungrouped) bucket. label:<key> buckets by the value of the given effective-label key, with hosts missing the key in an (unset) bucket. none returns one bucket per host (per-host shape). Unrecognised values fall back to hostgroup.

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "policies": [
    ],
  • "buckets": [
    ],
  • "edges": [
    ],
  • "meta": {
    }
}

Per-policy host reach summary (list columns)

Returns one row per policy with its active-host reach split by HOW a host is targeted, plus its rule count — the data behind the policies-list columns and the derived active/inert status. direct_hosts counts hosts matched by a direct block (a pinned host or a bare label/expression block); group_hosts counts hosts matched by a host-group block; total_hosts is the distinct hosts matched either way. A host can match both ways, so direct_hosts + group_hosts can exceed total_hosts — total_hosts is the true blast radius. Counts are over the active-host set (revoked and enrolling hosts excluded). rules_count is the policy's live rule count; a policy is considered inert when it reaches no host or carries no rule.

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a policy

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "priority": 0,
  • "selector": { },
  • "interface_names": [
    ],
  • "confirm_match_all": true,
  • "current_version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Update a policy (creates a version snapshot)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
name
required
string
description
string
priority
integer
selector
object
Array of objects
confirm_match_all
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "priority": 0,
  • "selector": { },
  • "rules": [
    ],
  • "confirm_match_all": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "priority": 0,
  • "selector": { },
  • "interface_names": [
    ],
  • "confirm_match_all": true,
  • "current_version": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Archive a policy

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Restore an archived policy (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Permanently purge an archived policy (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

List rules for a policy

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a rule

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
name
required
string
priority
integer
Default: 0
direction
string
Default: "ingress"
Enum: "ingress" "egress"
object (RuleMatch)

BPF match criteria. Unknown keys and unsupported protocol values are rejected with HTTP 400. Object-group references use arrays so every reference is stored in policy versions and restored atomically. Legacy singular *_set_id keys are accepted and returned as canonical one-element arrays.

state
string or null
Deprecated
states
Array of strings
Items Enum: "new" "established" "related" "invalid"

Set of conntrack states this rule matches (any of). Empty = stateless.

action
string
Default: "deny"
Enum: "allow" "deny" "log"
log
boolean
Default: false
silent
boolean
notrack
boolean
Default: false

Skip conntrack insert for flows this rule ALLOWs (saves LRU slots on high-volume stateless traffic). Does not change the verdict.

log_rate_limit_per_sec
integer <int32>
Default: 0

Per-rule log token bucket, events/sec. 0 means "use the fleet default" (AgentConfig.default_log_rate_limit_per_sec, 100/s) — NOT "no logging". The datapath field is 16-bit, so values above 65535 truncate.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "priority": 0,
  • "direction": "ingress",
  • "match": {
    },
  • "state": "string",
  • "states": [
    ],
  • "action": "allow",
  • "log": false,
  • "silent": true,
  • "notrack": false,
  • "log_rate_limit_per_sec": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",
  • "name": "string",
  • "priority": 0,
  • "direction": "ingress",
  • "match": {
    },
  • "state": "string",
  • "states": [
    ],
  • "action": "allow",
  • "log": true,
  • "silent": true,
  • "notrack": true,
  • "log_rate_limit_per_sec": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a rule

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
ruleID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",
  • "name": "string",
  • "priority": 0,
  • "direction": "ingress",
  • "match": {
    },
  • "state": "string",
  • "states": [
    ],
  • "action": "allow",
  • "log": true,
  • "silent": true,
  • "notrack": true,
  • "log_rate_limit_per_sec": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a rule

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
ruleID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
name
required
string
priority
integer
Default: 0
direction
string
Default: "ingress"
Enum: "ingress" "egress"
object (RuleMatch)

BPF match criteria. Unknown keys and unsupported protocol values are rejected with HTTP 400. Object-group references use arrays so every reference is stored in policy versions and restored atomically. Legacy singular *_set_id keys are accepted and returned as canonical one-element arrays.

state
string or null
Deprecated
states
Array of strings
Items Enum: "new" "established" "related" "invalid"

Set of conntrack states this rule matches (any of). Empty = stateless.

action
string
Default: "deny"
Enum: "allow" "deny" "log"
log
boolean
Default: false
silent
boolean
notrack
boolean
Default: false

Skip conntrack insert for flows this rule ALLOWs (saves LRU slots on high-volume stateless traffic). Does not change the verdict.

log_rate_limit_per_sec
integer <int32>
Default: 0

Per-rule log token bucket, events/sec. 0 means "use the fleet default" (AgentConfig.default_log_rate_limit_per_sec, 100/s) — NOT "no logging". The datapath field is 16-bit, so values above 65535 truncate.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "priority": 0,
  • "direction": "ingress",
  • "match": {
    },
  • "state": "string",
  • "states": [
    ],
  • "action": "allow",
  • "log": false,
  • "silent": true,
  • "notrack": false,
  • "log_rate_limit_per_sec": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "policy_id": "ee9b03e0-6495-427a-85a5-34444d24ae04",
  • "name": "string",
  • "priority": 0,
  • "direction": "ingress",
  • "match": {
    },
  • "state": "string",
  • "states": [
    ],
  • "action": "allow",
  • "log": true,
  • "silent": true,
  • "notrack": true,
  • "log_rate_limit_per_sec": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a rule

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
ruleID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Dry-run preview — compute host impact without applying

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
required
Array of objects (DryRunRuleSpec)
Array
id
string <uuid>

Existing rule UUID; omit for new rules

name
string
priority
integer
direction
string
Enum: "ingress" "egress"
object (RuleMatch)

BPF match criteria. Unknown keys and unsupported protocol values are rejected with HTTP 400. Object-group references use arrays so every reference is stored in policy versions and restored atomically. Legacy singular *_set_id keys are accepted and returned as canonical one-element arrays.

state
string or null
Deprecated
states
Array of strings
Items Enum: "new" "established" "related" "invalid"

Set of conntrack states this rule matches (any of). Empty = stateless.

action
string
Enum: "allow" "deny" "log"
log
boolean
silent
boolean
notrack
boolean

Skip conntrack insert for flows this rule ALLOWs (saves LRU slots on high-volume stateless traffic). Does not change the verdict.

log_rate_limit_per_sec
integer <int32>

Per-rule log token bucket, events/sec. 0 means "use the fleet default" (AgentConfig.default_log_rate_limit_per_sec, 100/s) — NOT "no logging".

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "affected_count": 0,
  • "hosts": [
    ]
}

List version snapshots for a policy

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List pending policy drafts

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stage a policy draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Discard a policy draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftId
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Write-free blast preview of a staged draft (B-12)

Computes the affected-host impact of a staged draft WITHOUT writing, enriched with the observed traffic (decisions) for the affected before-side rules over a bounded window. Read tier (writes nothing) — POST because it echoes the projected draft content. The identical route is mounted on object_groups and host_groups (shared version registrar). Optional from/to bound the traffic window (default 24h, capped 7d server-side, partition-pruned).

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftId
required
string <uuid>
query Parameters
from
string <date-time>

Traffic window start (RFC3339); defaulted/capped server-side.

to
string <date-time>

Traffic window end (RFC3339); defaults to now.

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "blast": {
    },
  • "traffic": [
    ],
  • "window": {
    }
}

Apply a policy draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftId
required
string <uuid>
query Parameters
confirm_match_all
boolean
Default: false
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Revert policy to a previous version

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
v
required
integer
query Parameters
confirm_match_all
boolean
Default: false
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "status": "reverted",
  • "version": 0
}

Versions

Cross-entity config-version browser and impact preview

List applied config versions across all entity types (VERLIVE-03)

Tenant-scoped cross-entity browse of applied config_versions (policy, objectgroup, host_group, host_labels). Filter by optional entity type + created_at range; newest-first, LIMIT-capped. The display name is resolved from the version's content snapshot as-of that version (no JOIN). Read tier.

Authorizations:
cookieAuthbearerAuth
query Parameters
type
string
Enum: "policy" "objectgroup" "host_group" "host_labels"

Filter by entity type; omitted = all types. Unknown value → 400.

from
string <date-time>

Inclusive lower bound on created_at (RFC3339).

to
string <date-time>

Exclusive upper bound on created_at (RFC3339).

limit
integer

Max rows (default 200, capped 1000).

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Preview the COMBINED impact of a set of applied versions (B-11)

Read-only combined impact preview for a SET of selected applied versions, in a single round-trip. Runs the per-host match-aware blast once per version and returns ONE observed-traffic aggregate over the UNION of their before-side rule ids over a bounded window (default 24h, capped 7d server-side, partition-pruned) — so a rule observed by two selected versions over the shared window is counted exactly once (no cross-version double-count) and N HTTP round-trips collapse to one. Preview-only — stages/applies/signs nothing. Repeated ids param (NOT comma-joined). A cross-tenant/missing/malformed id is silently OMITTED from the batch (partial results are valid), never a 404. An absent ids param is a 400.

Authorizations:
cookieAuthbearerAuth
query Parameters
ids
required
Array of strings <uuid> [ items <uuid > ]

Applied-version ids to combine — repeated once per version (?ids=A&ids=B), NOT comma-joined. Absent → 400.

from
string <date-time>

Traffic window start (RFC3339); defaulted/capped server-side.

to
string <date-time>

Traffic window end (RFC3339); defaults to now.

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ],
  • "traffic": [
    ],
  • "window": {
    }
}

Preview the impact of an applied version (VERLIVE-04/05)

Read-only impact preview for a selected applied version. Computes the per-host match-aware before/after ruleset diff (before = current effective ruleset, after = the version's snapshot) and attaches observed log_events traffic (decisions) for the affected BEFORE-side rule ids over a bounded window (default 24h, capped 7d server-side, partition-pruned). Preview-only — it stages/applies/signs nothing. A cross-tenant/missing id returns 404.

Authorizations:
cookieAuthbearerAuth
path Parameters
versionID
required
string <uuid>
query Parameters
from
string <date-time>

Traffic window start (RFC3339); defaulted/capped server-side.

to
string <date-time>

Traffic window end (RFC3339); defaults to now.

breakdown_by
string
Default: "port"
Enum: "port" "peer" "port_peer"

B-09 traffic breakdown preset. Whitelisted; default port ((rule, protocol, dst_port)). peer groups by (rule, src_ip); port_peer by (rule, protocol, dst_port, src_ip). An unknown value is a 400.

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  • "entity_type": "string",
  • "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  • "version": 0,
  • "blast": { },
  • "traffic": [
    ],
  • "breakdown": [
    ],
  • "window": {
    }
}

Compare two versions of the same entity (B-10, past → future diff)

Read-only TWO-POINT comparison of versions A (past) and B (future) of the SAME entity. Unlike /versions/{id}/impact (which always diffs against the current live ruleset), compare diffs two arbitrary snapshots directly. For a policy it returns the OG-AWARE spec-level field diff (added/removed/changed with per-field before→after on resolved src/dst CIDRs, ports, protocol, tcp_flags, state, action) — object-group references are expanded so a rule differing only in a referenced group's membership classifies changed, not "No changes". For object_group/host_group/host_labels it returns the member set-diff (members_added/members_removed) with an empty diff. Both snapshots are upgraded via ToCurrent before diffing so an older content_version on A is not mis-diffed against a newer B. Side semantics: added = present in B not A; removed = in A not B; compare(A,B) and compare(B,A) are mirror images. Traffic (decisions) is attached for the A-SIDE rule ids over a bounded window and is empty when snapshot A carries no stable rule ids. Preview-only — it stages/applies/signs nothing. A and B MUST belong to the same entity (else 400); a missing/cross-tenant version returns 404.

Authorizations:
cookieAuthbearerAuth
query Parameters
a
required
string <uuid>

Version id of side A (the "past" snapshot).

b
required
string <uuid>

Version id of side B (the "future"/other snapshot).

from
string <date-time>

Traffic window start (RFC3339); defaulted/capped server-side.

to
string <date-time>

Traffic window end (RFC3339); defaults to now.

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "entity_type": "string",
  • "entity_id": "8161163a-f227-466f-bc01-090a01e80165",
  • "a": {
    },
  • "b": {
    },
  • "diff": { },
  • "members_added": [
    ],
  • "members_removed": [
    ],
  • "traffic": [
    ],
  • "window": {
    }
}

ObjectGroups

Named IP/port/host sets for use in rules

List object groups

Authorizations:
cookieAuthbearerAuth
query Parameters
changed_since
string <date-time>

Reconnect-backfill delta cursor (UI live-sync). When present, the endpoint returns ONLY rows changed at or after changed_since - OVERLAP (a small server-applied safety window; client dedups by id), tenant-scoped exactly as the full list. Omit for the normal full-list response (unchanged). Format is RFC3339 with nanosecond precision (RFC3339Nano) so same-second bulk-enroll ties are preserved. For hosts, archived (soft-deleted) rows are surfaced as tombstones (archived_at set) so clients reconcile deletes. For tokens the filter is insert-only (bootstrap_tokens key on created_at).

type
string
Enum: "ipset" "portset" "hostset"
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an object group

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
type
required
string
Enum: "ipset" "portset" "hostset"
name
required
string
spec
object

Responses

Request samples

Content type
application/json
{
  • "type": "ipset",
  • "name": "string",
  • "spec": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "type": "ipset",
  • "name": "string",
  • "spec": { },
  • "resolved_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Get an object group

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "type": "ipset",
  • "name": "string",
  • "spec": { },
  • "resolved_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Update object group spec

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
spec
required
object

Responses

Request samples

Content type
application/json
{
  • "spec": { }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "type": "ipset",
  • "name": "string",
  • "spec": { },
  • "resolved_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Archive an object group

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

List archived object groups (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Restore an archived object group (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Permanently purge an archived object group (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

List applied object-group config versions

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Revert an object group to an applied version (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
v
required
integer >= 1
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

List pending object-group drafts

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stage an object-group draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Discard an object-group draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Preview the impact of an object-group draft without applying it

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "blast": {
    },
  • "traffic": [
    ],
  • "window": {
    }
}

Apply an object-group draft (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
draftID
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Tokens

Agent enrollment tokens

List enrollment tokens

Authorizations:
cookieAuthbearerAuth
query Parameters
changed_since
string <date-time>

Reconnect-backfill delta cursor (UI live-sync). When present, the endpoint returns ONLY rows changed at or after changed_since - OVERLAP (a small server-applied safety window; client dedups by id), tenant-scoped exactly as the full list. Omit for the normal full-list response (unchanged). Format is RFC3339 with nanosecond precision (RFC3339Nano) so same-second bulk-enroll ties are preserved. For hosts, archived (soft-deleted) rows are surfaced as tombstones (archived_at set) so clients reconcile deletes. For tokens the filter is insert-only (bootstrap_tokens key on created_at).

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an enrollment token

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
type
required
string
Enum: "single_host" "bulk"
target_host_id
string <uuid>

Required when type=single_host

target_group_id
string <uuid>

bulk only — auto-add the enrolling host to this host-group (must be in tenant)

object
ttl_seconds
integer
Default: 3600
max_uses
integer
Default: 1

Responses

Request samples

Content type
application/json
{
  • "type": "single_host",
  • "target_host_id": "5fa08e70-cef9-414c-b387-7bde7b6f4011",
  • "target_group_id": "efc47beb-e46d-465e-921d-3e02578ccf22",
  • "label_template": {
    },
  • "ttl_seconds": 3600,
  • "max_uses": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "type": "single_host",
  • "target_host_id": "5fa08e70-cef9-414c-b387-7bde7b6f4011",
  • "target_group_id": "efc47beb-e46d-465e-921d-3e02578ccf22",
  • "label_template": {
    },
  • "max_uses": 0,
  • "uses_count": 0,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "token": "string"
}

Revoke an enrollment token

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

DefaultPolicy

Tenant-level default allow/deny actions

AuditLog

API audit trail

List audit log entries

Authorizations:
cookieAuthbearerAuth
query Parameters
start
string <date-time>
end
string <date-time>
limit
integer <= 10000
Default: 500
actor_type
Array of strings
Items Enum: "user" "api_token" "system" "agent"

Actor kind(s) to include. Repeatable (?actor_type=user&actor_type=agent) — values are unioned server-side (OR). A single value stays valid.

actor_id
Array of strings <uuid> [ items <uuid > ]

Actor UUID(s) to include. Repeatable (?actor_id=a&actor_id=b) — values are unioned server-side (OR). A single value stays valid (backward-compatible).

object_type
string
object_id
string <uuid>
q
string

Free-text filter — case-insensitive substring match over the action string.

header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Users

User management (Admin role required for mutations)

List users

Authorizations:
cookieAuthbearerAuth
query Parameters
changed_since
string <date-time>

Reconnect-backfill delta cursor (UI live-sync). When present, the endpoint returns ONLY rows changed at or after changed_since - OVERLAP (a small server-applied safety window; client dedups by id), tenant-scoped exactly as the full list. Omit for the normal full-list response (unchanged). Format is RFC3339 with nanosecond precision (RFC3339Nano) so same-second bulk-enroll ties are preserved. For hosts, archived (soft-deleted) rows are surfaced as tombstones (archived_at set) so clients reconcile deletes. For tokens the filter is insert-only (bootstrap_tokens key on created_at).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a user (Admin only)

Authorizations:
cookieAuthbearerAuth
Request Body schema: application/json
required
username
required
string
email
required
string <email>
password
required
string <password>
role
required
string
Enum: "admin" "editor" "auditor"

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "status": "active",
  • "role": "admin",
  • "is_oidc": true,
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

List archived users (Admin only)

Authorizations:
cookieAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a user

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "status": "active",
  • "role": "admin",
  • "is_oidc": true,
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Update user status or password (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
status
string
Enum: "active" "suspended"
password
string <password>

Responses

Request samples

Content type
application/json
{
  • "status": "active",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "username": "string",
  • "email": "string",
  • "status": "active",
  • "role": "admin",
  • "is_oidc": true,
  • "last_login_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z"
}

Archive a user and invalidate its sessions (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Get user role

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "role": "admin"
}

Set user role (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
required
role
required
string
Enum: "admin" "editor" "auditor"

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "role": "admin"
}

Restore an archived user (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Permanently purge an archived user after the retention window (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

APITokens

Long-lived API tokens for automation

List API tokens

Authorizations:
cookieAuthbearerAuth
query Parameters
changed_since
string <date-time>

Reconnect-backfill delta cursor (UI live-sync). When present, the endpoint returns ONLY rows changed at or after changed_since - OVERLAP (a small server-applied safety window; client dedups by id), tenant-scoped exactly as the full list. Omit for the normal full-list response (unchanged). Format is RFC3339 with nanosecond precision (RFC3339Nano) so same-second bulk-enroll ties are preserved. For hosts, archived (soft-deleted) rows are surfaced as tombstones (archived_at set) so clients reconcile deletes. For tokens the filter is insert-only (bootstrap_tokens key on created_at).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an API token

Authorizations:
cookieAuthbearerAuth
Request Body schema: application/json
required
name
required
string
role
required
string
Enum: "admin" "editor" "auditor"
expires_at
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "admin",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "role": "admin",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "archived_at": "2019-08-24T14:15:22Z",
  • "token": "string"
}

List archived API tokens (Admin only)

Authorizations:
cookieAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Archive and revoke an API token

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>

Responses

Restore an archived API token (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

Permanently purge an archived API token after the retention window (Admin only)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "request_id": "string"
}

GroupingChains

Saved host-label grouping presets

List system and personal grouping chains

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a personal grouping chain (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Request Body schema: application/json
required
name
required
string
keys
required
Array of strings [ 1 .. 5 ] items unique

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "keys": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "name": "string",
  • "keys": [
    ],
  • "is_system": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a personal grouping chain (Admin or Editor)

Authorizations:
cookieAuthbearerAuth
path Parameters
id
required
string <uuid>
header Parameters
X-Tenant-ID
required
string <uuid>

Tenant UUID

Responses