/v1/admin/analytics

GET /v1/admin/analytics/blocked-ip-count

Count distinct client IPs blocked by the global firewall or CC auto-bans

operationId

getPlatformAnalyticsBlockedIPCount

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Requires a platform-scoped identity with sites.read or platform.admin. Counts distinct client_ip values from global_firewall block events and CC temporary_ban events in the left-closed, right-open window and is bounded by one ingestion snapshot. It is not the current ACL cardinality.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/blocked-ip-trend

Read the hourly distinct client IPs blocked by the global firewall

operationId

getPlatformAnalyticsBlockedIPTrend

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Requires a platform-scoped identity with sites.read or platform.admin. Each returned UTC bucket contains the distinct client_ip count from global_firewall block events, bounded by one ingestion snapshot.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/connections/dead-letters

List durable analytics connections dead-letter receipts

operationId

listPlatformAnalyticsConnectionsDeadLetters

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read platform.admin

Description (from the contract)

Requires a revocable platform Bearer session with sites.read and platform.admin. An optional tenant_id narrows the digest-only durable receipt projection to one tenant. Raw payloads are never returned.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/connections/dead-letters/{dead_letter_id}

Read one durable analytics connections dead-letter receipt

operationId

getPlatformAnalyticsConnectionsDeadLetter

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read platform.admin

Description (from the contract)

Requires a revocable platform Bearer session with sites.read and platform.admin. The response is a digest-only durable receipt and never includes raw payload or secret fields.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/connections/retention

Read finalized connections retention facts for a tenant subscription

operationId

getPlatformAnalyticsConnectionsRetention

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read platform.admin

Description (from the contract)

Requires a revocable platform Bearer session with sites.read and platform.admin. Tenant and subscription scope are mandatory and every returned fact is finalized, evidence-bound, and ordered by UTC period.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/hourly-trend

Read a platform or explicitly selected tenant hourly trend

operationId

getPlatformAnalyticsHourlyTrend

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Requires a platform-scoped identity with sites.read or platform.admin. Buckets are UTC hours and only buckets containing events are returned.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/l4-realtime

operationId

getAdminL4Realtime

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/access

List access logs for one explicitly selected tenant

operationId

listPlatformAccessLogs

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Requires a platform-scoped identity. tenant_id is mandatory; this API never performs an all-tenant log query. URI output contains only an origin-form path and omits query and fragment content.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/access/exports

List durable access-log exports owned by the calling account for the target tenant

operationId

listPlatformAccessLogExports

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Without query filters, lists up to 50 exports owned by the calling account (user + access scope), regardless of the login session that created them. With from/to (and the same filters as the access-log list, without limit/cursor), returns at most one export: the latest generation for that account and normalized query scope, so the log view can recover it after re-login.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/analytics/logs/access/exports

Create a snapshot-bound access-log export for one target tenant

operationId

createPlatformAccessLogExport

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Idempotent per account (user + access scope) and normalized query scope, independent of the login session. The same Idempotency-Key replays its export (409 if the key was used for another scope). For the same scope, a pending, running or unexpired completed export is reused (Idempotency-Replayed: true); a failed export with attempts left is retried in place under the same export id; otherwise a new generation is created.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/access/exports/{export_id}

operationId

getPlatformAccessLogExport

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/access/exports/{export_id}/download

operationId

downloadPlatformAccessLogExport

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/analytics/logs/access/exports/{export_id}/download-grants

operationId

grantPlatformAccessLogExportDownload

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Returns a short-lived one-time token bound to the current platform session, target tenant and export. Any session of the owning account may request a grant; a token from another session is rejected. Only its SHA-256 digest is stored.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/block-events

List security block events for one explicitly selected tenant

operationId

listPlatformBlockEvents

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Requires a platform-scoped identity and an explicit tenant_id. Returns the current security-event projection with the same snapshot-bounded opaque cursor contract as access logs. This is raw event retrieval, not an immutable block-state transition history.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/blocks/current

List current ACL blocks across the customer control plane

operationId

listPlatformCurrentBlocks

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Returns only CIDRs present in the active site ACL policy. A newer unpublished policy revision or open activation makes the item non-unlockable. tenant_id optionally narrows the platform-wide read; every row carries its tenant_id so write actions stay explicitly scoped.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/blocks/current-count

Count current ACL blocks by site across the customer control plane

operationId

countPlatformCurrentBlocksBySite

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/analytics/logs/blocks/current/{block_id}/unlock

Unlock one current ACL block for an explicitly selected tenant

operationId

unlockPlatformCurrentBlock

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：security_policies.manage

Description (from the contract)

Removes exactly one CIDR from a new ACL policy revision, then starts a version-fenced edge activation. A stale active revision, open activation, missing target CIDR, or missing target-node snapshot fails closed with 409. Reusing the same key and body returns the same durable result; a conflicting body is rejected.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/blocks/history

List audited unlock history across the customer control plane

operationId

listPlatformBlockHistory

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Returns append-only cidr_unlock activation audit facts and their latest durable edge rollout progress. tenant_id optionally narrows the platform-wide read.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/cc-coordination

List cross-node CC coordination states of every tenant, optionally narrowed to one tenant or site

operationId

listPlatformCCCoordinationStates

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/analytics/logs/cc-coordination/{state_id}/release

Release one exact cross-node CC state after a false-positive decision

operationId

releasePlatformCCCoordinationState

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：security_policies.manage

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/logs/{kind}/geo-evidence/{event_id}

Reconcile one tenant log fact against a verified GeoIP catalog

operationId

getPlatformAnalyticsGeoEvidence

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/market-security

List relayed market supply attack log lines of any tenant

operationId

listAdminMarketSecurityLogs

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：platform.admin

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/site-monitoring

Read one tenant's site monitoring as a platform administrator

operationId

getPlatformSiteMonitoring

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：platform.admin

Description (from the contract)

Requires a platform session with platform.admin and exactly one canonical tenant_id. Omitting, duplicating, or changing tenant scope through identity headers is rejected before any source is queried.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/site-quality-diagnostics

Read one tenant's quality diagnostics from the platform scope

operationId

getPlatformQualityDiagnostics

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：platform.admin

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/site-realtime

Read platform-wide or one tenant's finalized site realtime facts

operationId

getPlatformSiteRealtime

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Requires a platform identity with sites.read or platform.admin. Omitting tenant_id queries all tenants; providing it narrows the query to one tenant. With query_version=2 the exact minute-aligned [from,to) interval is projected without rounding. Without query_version, legacy hour alignment and the original response keys are preserved. Its enclosing complete UTC hours must first have independent PostgreSQL source coverage; their expected counts are reconciled with a single ClickHouse access scan shared by all exact-range projections.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/summary

Read a platform or explicitly selected tenant analytics summary

operationId

getPlatformAnalyticsSummary

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Requires a platform-scoped identity with sites.read or platform.admin. Omitting tenant_id queries all tenants; providing tenant_id narrows the query to that tenant. The time window is left-closed and right-open.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/analytics/top/{dimension}

Page through a platform or explicitly selected tenant ranking

operationId

getPlatformAnalyticsTop

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：sites.read

Description (from the contract)

Requires a platform-scoped identity with sites.read or platform.admin. The cursor is bound to scope, filters, dimension, and one ingestion snapshot. The ja4 dimension is reserved but unsupported in v1.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list