Tiyi v3.8.0

system.proto — System settings, health, dashboards, updates, and declarative apply

Schema: tiyi.v1 · system.proto · English guide · 中文指南 · Full RPC index

Services

SystemService

RPC	Kind	Required permission
`Health`	unary	(`system:read`)
`Version`	unary	authenticated
`GetSystemSettings`	unary	(`system:read`)
`UpdateSystemSettings`	unary	(`system:write`)
`ImportLicense`	unary	(`system:write`)
`GetDashboardStats`	unary	(`site:read`)
`GetDashboardOverview`	unary	`site:read` and `telemetry:read`
`GetTrafficTimeseries`	unary	(`site:read`)
`GetAttackDistribution`	unary	(`site:read`)
`GetTopAttackers`	unary	(`site:read`)
`PreviewApply`	unary	(`system:apply`)
`Apply`	unary	(`system:apply`)
`ListBinaryReleases`	unary	(`system:update:read`)
`GetBinaryRelease`	unary	(`system:update:read`)
`ImportBinaryRelease`	unary	(`system:update:write`)
`DeleteBinaryRelease`	unary	(`system:update:write`)
`ApplyBinaryRelease`	unary	(`system:update:apply`)
`RollbackBinaryRelease`	unary	(`system:update:apply`)
`ListSystemCrsRulesets`	unary	(`system:update:read`)
`GetSystemCrsRuleset`	unary	(`system:update:read`)
`ImportCrsRuleset`	unary	(`system:update:write`)
`DeleteCrsRuleset`	unary	(`system:update:write`)
`ListUpgradeRuns`	unary	(`system:update:read`)
`GetUpgradeRun`	unary	(`system:update:read`)
`StreamUpgradeRun`	server stream	(`system:update:read`)
`CancelUpgradeRun`	unary	(`system:update:apply`)
`CheckForUpdates`	unary	(`system:update:read`)
`ListUpstreamCrsReleases`	unary	(`system:update:read`)
`GetObservationPipelineStats`	unary	(`system:read`)
`ListGeoDatabases`	unary	(`system:update:read`)
`DownloadGeoDatabase`	unary	(`system:update:write`)
`UploadGeoDatabase`	unary	(`system:update:write`)
`DeleteGeoDatabase`	unary	(`system:update:write`)

RPCs

SystemService.Health

Procedure POST /tiyi.v1.SystemService/Health
Kind unary
Auth (system:read)

Request — tiyi.v1.HealthRequest

No fields — send {}.

Response — tiyi.v1.HealthResponse

Field	JSON key	Type	Cardinality	Description
`status`	`status`	`string`	singular	—
`version`	`version`	`string`	singular	—
`controller_id`	`controllerId`	`string`	singular	—
`deployment_id`	`deploymentId`	`string`	singular	—
`checks`	`checks`	`SystemHealthCheck`	repeated	—
`checked_at`	`checkedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`config_revision`	`configRevision`	`int64`	singular	JSON string (64-bit ints are quoted).
`active_sites`	`activeSites`	`int32`	singular	—
`remote_agents_connected`	`remoteAgentsConnected`	`int32`	singular	—

SystemService.Version

Procedure POST /tiyi.v1.SystemService/Version
Kind unary
Auth authenticated

Request — tiyi.v1.VersionRequest

No fields — send {}.

Response — tiyi.v1.VersionResponse

Field	JSON key	Type	Cardinality	Description
`build`	`build`	`BuildInfo`	singular	—
`license`	`license`	`LicenseStatus`	singular	LICENSE-GATE

SystemService.GetSystemSettings

Procedure POST /tiyi.v1.SystemService/GetSystemSettings
Kind unary
Auth (system:read)

Request — tiyi.v1.GetSystemSettingsRequest

No fields — send {}.

Response — tiyi.v1.GetSystemSettingsResponse

Field	JSON key	Type	Cardinality	Description
`settings`	`settings`	`SystemSettings`	singular	—

SystemService.UpdateSystemSettings

Procedure POST /tiyi.v1.SystemService/UpdateSystemSettings
Kind unary
Auth (system:write)

Request — tiyi.v1.UpdateSystemSettingsRequest

Field	JSON key	Type	Cardinality	Description
`values`	`values`	`google.protobuf.Struct`	singular	free-form JSON object.

Response — tiyi.v1.UpdateSystemSettingsResponse

Field	JSON key	Type	Cardinality	Description
`settings`	`settings`	`SystemSettings`	singular	—
`application`	`application`	`string`	singular	The settings have committed. Application is separate from persistence.
`apply_error`	`applyError`	`string`	singular	—

SystemService.ImportLicense

LICENSE-GATE

Procedure POST /tiyi.v1.SystemService/ImportLicense
Kind unary
Auth (system:write)

Request — tiyi.v1.ImportLicenseRequest

Field	JSON key	Type	Cardinality	Description
`license`	`license`	`bytes`	singular	raw bytes of the signed license file. base64-encoded JSON string.

Response — tiyi.v1.ImportLicenseResponse

Field	JSON key	Type	Cardinality	Description
`status`	`status`	`LicenseStatus`	singular	the resulting (verified, possibly expired) status.

SystemService.GetDashboardStats

Procedure POST /tiyi.v1.SystemService/GetDashboardStats
Kind unary
Auth (site:read)

Request — tiyi.v1.GetDashboardStatsRequest

No fields — send {}.

Response — tiyi.v1.GetDashboardStatsResponse

Field	JSON key	Type	Cardinality	Description
`stats`	`stats`	`DashboardStats`	singular	—

SystemService.GetDashboardOverview

Returns the complete dashboard read model in one bounded request. The richer telemetry rankings require both site and telemetry visibility.

Procedure POST /tiyi.v1.SystemService/GetDashboardOverview
Kind unary
Auth site:read and telemetry:read

Request — tiyi.v1.GetDashboardOverviewRequest

Field	JSON key	Type	Cardinality	Description
`time_range`	`timeRange`	`TimeRange`	singular	—
`bucket_size`	`bucketSize`	`string`	singular	—
`site_id`	`siteId`	`string`	singular	—
`top_k_limit`	`topKLimit`	`int32`	singular	Applies to every ranking. The server defaults to 10 and caps at 100.

Response — tiyi.v1.GetDashboardOverviewResponse

Field	JSON key	Type	Cardinality	Description
`time_range`	`timeRange`	`TimeRange`	singular	Actual immutable snapshot scope, including when a cached response is served.
`traffic_bucket_seconds`	`trafficBucketSeconds`	`int64`	singular	JSON string (64-bit ints are quoted).
`stats`	`stats`	`DashboardStats`	singular	—
`traffic`	`traffic`	`TrafficPoint`	repeated	—
`attack_distribution`	`attackDistribution`	`AttackDistributionItem`	repeated	—
`top_attackers`	`topAttackers`	`TopAttacker`	repeated	—
`top_statuses`	`topStatuses`	`DashboardTopK`	singular	—
`top_paths`	`topPaths`	`DashboardTopK`	singular	—
`top_user_agents`	`topUserAgents`	`DashboardTopK`	singular	—
`top_sites`	`topSites`	`DashboardTopSite`	repeated	Empty for a site-scoped request: ranking one selected site against itself is not useful and preserving this distinction avoids a semantic surprise when the operator changes the dashboard site selector.
`other_sites_total`	`otherSitesTotal`	`int64`	singular	JSON string (64-bit ints are quoted).
`security_top_attackers`	`securityTopAttackers`	`DashboardSecurityTopK`	singular	SecurityFact-derived rankings. These are separate from the all-traffic top_paths/top_sites fields above so their semantics cannot be confused.
`security_top_sites`	`securityTopSites`	`DashboardSecurityTopK`	singular	—
`security_top_targets`	`securityTopTargets`	`DashboardSecurityTopK`	singular	—
`security_top_attack_types`	`securityTopAttackTypes`	`DashboardSecurityTopK`	singular	—
`security_top_rules`	`securityTopRules`	`DashboardSecurityTopK`	singular	—
`security_top_methods`	`securityTopMethods`	`DashboardSecurityTopK`	singular	—
`freshness`	`freshness`	`DashboardFreshness`	singular	—
`traffic_quality`	`trafficQuality`	`DashboardTrafficQuality`	singular	—
`top_methods`	`topMethods`	`DashboardTopK`	singular	—
`top_http_versions`	`topHttpVersions`	`DashboardTopK`	singular	—
`top_transport_versions`	`topTransportVersions`	`DashboardTopK`	singular	—
`security_top_countries`	`securityTopCountries`	`DashboardSecurityTopK`	singular	Country distribution derived from the bounded attacker heavy-hitter set. other_count includes attackers outside that set and IPs that cannot be resolved by the currently installed Country database.

SystemService.GetTrafficTimeseries

Procedure POST /tiyi.v1.SystemService/GetTrafficTimeseries
Kind unary
Auth (site:read)

Request — tiyi.v1.GetTrafficTimeseriesRequest

Field	JSON key	Type	Cardinality	Description
`time_range`	`timeRange`	`TimeRange`	singular	—
`bucket_size`	`bucketSize`	`string`	singular	—
`site_id`	`siteId`	`string`	singular	—

Response — tiyi.v1.GetTrafficTimeseriesResponse

Field	JSON key	Type	Cardinality	Description
`points`	`points`	`TrafficPoint`	repeated	—

SystemService.GetAttackDistribution

Procedure POST /tiyi.v1.SystemService/GetAttackDistribution
Kind unary
Auth (site:read)

Request — tiyi.v1.GetAttackDistributionRequest

Field	JSON key	Type	Cardinality	Description
`time_range`	`timeRange`	`TimeRange`	singular	—
`limit`	`limit`	`int32`	singular	—
`site_id`	`siteId`	`string`	singular	—

Response — tiyi.v1.GetAttackDistributionResponse

Field	JSON key	Type	Cardinality	Description
`items`	`items`	`AttackDistributionItem`	repeated	—

SystemService.GetTopAttackers

Procedure POST /tiyi.v1.SystemService/GetTopAttackers
Kind unary
Auth (site:read)

Request — tiyi.v1.GetTopAttackersRequest

Field	JSON key	Type	Cardinality	Description
`time_range`	`timeRange`	`TimeRange`	singular	—
`limit`	`limit`	`int32`	singular	—
`site_id`	`siteId`	`string`	singular	—

Response — tiyi.v1.GetTopAttackersResponse

Field	JSON key	Type	Cardinality	Description
`items`	`items`	`TopAttacker`	repeated	—

SystemService.PreviewApply

Procedure POST /tiyi.v1.SystemService/PreviewApply
Kind unary
Auth (system:apply)

Request — tiyi.v1.PreviewApplyRequest

Field	JSON key	Type	Cardinality	Description
`manifest_yaml`	`manifestYaml`	`bytes`	singular	base64-encoded JSON string.

Response — tiyi.v1.PreviewApplyResponse

Field	JSON key	Type	Cardinality	Description
`plan`	`plan`	`ApplyPlan`	singular	—

SystemService.Apply

Procedure POST /tiyi.v1.SystemService/Apply
Kind unary
Auth (system:apply)

Request — tiyi.v1.ApplyRequest

Field	JSON key	Type	Cardinality	Description
`manifest_yaml`	`manifestYaml`	`bytes`	singular	base64-encoded JSON string.
`dry_run`	`dryRun`	`bool`	singular	—

Response — tiyi.v1.ApplyResponse

Field	JSON key	Type	Cardinality	Description
`plan`	`plan`	`ApplyPlan`	singular	—
`results`	`results`	`MutationResult`	repeated	—

SystemService.ListBinaryReleases

Procedure POST /tiyi.v1.SystemService/ListBinaryReleases
Kind unary
Auth (system:update:read)

Request — tiyi.v1.ListBinaryReleasesRequest

Field	JSON key	Type	Cardinality	Description
`page`	`page`	`PageRequest`	singular	—

Response — tiyi.v1.ListBinaryReleasesResponse

Field	JSON key	Type	Cardinality	Description
`items`	`items`	`BinaryRelease`	repeated	—
`page`	`page`	`PageResponse`	singular	—

SystemService.GetBinaryRelease

Procedure POST /tiyi.v1.SystemService/GetBinaryRelease
Kind unary
Auth (system:update:read)

Request — tiyi.v1.GetBinaryReleaseRequest

Field	JSON key	Type	Cardinality	Description
`id`	`id`	`string`	singular	—

Response — tiyi.v1.GetBinaryReleaseResponse

Field	JSON key	Type	Cardinality	Description
`release`	`release`	`BinaryRelease`	singular	—

SystemService.ImportBinaryRelease

Procedure POST /tiyi.v1.SystemService/ImportBinaryRelease
Kind unary
Auth (system:update:write)

Request — tiyi.v1.ImportBinaryReleaseRequest

Field	JSON key	Type	Cardinality	Description
`tarball`	`tarball`	`bytes`	singular	base64-encoded JSON string.
`source_url`	`sourceUrl`	`string`	singular	—

Response — tiyi.v1.ImportBinaryReleaseResponse

Field	JSON key	Type	Cardinality	Description
`release`	`release`	`BinaryRelease`	singular	—

SystemService.DeleteBinaryRelease

Procedure POST /tiyi.v1.SystemService/DeleteBinaryRelease
Kind unary
Auth (system:update:write)

Request — tiyi.v1.DeleteBinaryReleaseRequest

Field	JSON key	Type	Cardinality	Description
`id`	`id`	`string`	singular	—

Response — tiyi.v1.DeleteBinaryReleaseResponse

Field	JSON key	Type	Cardinality	Description
`result`	`result`	`MutationResult`	singular	—

SystemService.ApplyBinaryRelease

Procedure POST /tiyi.v1.SystemService/ApplyBinaryRelease
Kind unary
Auth (system:update:apply)

Request — tiyi.v1.ApplyBinaryReleaseRequest

Field	JSON key	Type	Cardinality	Description
`release_id`	`releaseId`	`string`	singular	—
`agent_ids`	`agentIds`	`string`	repeated	—

Response — tiyi.v1.ApplyBinaryReleaseResponse

Field	JSON key	Type	Cardinality	Description
`run`	`run`	`UpgradeRun`	singular	—

SystemService.RollbackBinaryRelease

Procedure POST /tiyi.v1.SystemService/RollbackBinaryRelease
Kind unary
Auth (system:update:apply)

Request — tiyi.v1.RollbackBinaryReleaseRequest

Field	JSON key	Type	Cardinality	Description
`agent_ids`	`agentIds`	`string`	repeated	—

Response — tiyi.v1.RollbackBinaryReleaseResponse

Field	JSON key	Type	Cardinality	Description
`run`	`run`	`UpgradeRun`	singular	—

SystemService.ListSystemCrsRulesets

Procedure POST /tiyi.v1.SystemService/ListSystemCrsRulesets
Kind unary
Auth (system:update:read)

Request — tiyi.v1.ListSystemCrsRulesetsRequest

Field	JSON key	Type	Cardinality	Description
`page`	`page`	`PageRequest`	singular	—

Response — tiyi.v1.ListSystemCrsRulesetsResponse

Field	JSON key	Type	Cardinality	Description
`items`	`items`	`CrsRuleset`	repeated	—
`page`	`page`	`PageResponse`	singular	—

SystemService.GetSystemCrsRuleset

Procedure POST /tiyi.v1.SystemService/GetSystemCrsRuleset
Kind unary
Auth (system:update:read)

Request — tiyi.v1.GetSystemCrsRulesetRequest

Field	JSON key	Type	Cardinality	Description
`id`	`id`	`string`	singular	—

Response — tiyi.v1.GetSystemCrsRulesetResponse

Field	JSON key	Type	Cardinality	Description
`ruleset`	`ruleset`	`CrsRuleset`	singular	—

SystemService.ImportCrsRuleset

Procedure POST /tiyi.v1.SystemService/ImportCrsRuleset
Kind unary
Auth (system:update:write)

Request — tiyi.v1.ImportCrsRulesetRequest

Field	JSON key	Type	Cardinality	Description
`archive`	`archive`	`bytes`	singular	base64-encoded JSON string.
`source_url`	`sourceUrl`	`string`	singular	—
`github_tag`	`githubTag`	`string`	singular	When set, the server fetches the CRS release tarball from GitHub (https://github.com/coreruleset/coreruleset/releases/tag/), extracts it to a local cache, and imports the rules from there. Takes precedence over source_url when both are set.

Response — tiyi.v1.ImportCrsRulesetResponse

Field	JSON key	Type	Cardinality	Description
`ruleset`	`ruleset`	`CrsRuleset`	singular	—

SystemService.DeleteCrsRuleset

Procedure POST /tiyi.v1.SystemService/DeleteCrsRuleset
Kind unary
Auth (system:update:write)

Request — tiyi.v1.DeleteCrsRulesetRequest

Field	JSON key	Type	Cardinality	Description
`id`	`id`	`string`	singular	—

Response — tiyi.v1.DeleteCrsRulesetResponse

Field	JSON key	Type	Cardinality	Description
`result`	`result`	`MutationResult`	singular	—

SystemService.ListUpgradeRuns

Procedure POST /tiyi.v1.SystemService/ListUpgradeRuns
Kind unary
Auth (system:update:read)

Request — tiyi.v1.ListUpgradeRunsRequest

Field	JSON key	Type	Cardinality	Description
`page`	`page`	`PageRequest`	singular	—

Response — tiyi.v1.ListUpgradeRunsResponse

Field	JSON key	Type	Cardinality	Description
`items`	`items`	`UpgradeRun`	repeated	—
`page`	`page`	`PageResponse`	singular	—

SystemService.GetUpgradeRun

Procedure POST /tiyi.v1.SystemService/GetUpgradeRun
Kind unary
Auth (system:update:read)

Request — tiyi.v1.GetUpgradeRunRequest

Field	JSON key	Type	Cardinality	Description
`id`	`id`	`string`	singular	—

Response — tiyi.v1.GetUpgradeRunResponse

Field	JSON key	Type	Cardinality	Description
`run`	`run`	`UpgradeRun`	singular	—

SystemService.StreamUpgradeRun

Procedure POST /tiyi.v1.SystemService/StreamUpgradeRun
Kind server stream — server-streaming; the response is a stream of messages
Auth (system:update:read)

Request — tiyi.v1.StreamUpgradeRunRequest

Field	JSON key	Type	Cardinality	Description
`run_id`	`runId`	`string`	singular	—

Response — tiyi.v1.StreamUpgradeRunResponse

Field	JSON key	Type	Cardinality	Description
`event`	`event`	`UpgradeRunEvent`	singular	—

SystemService.CancelUpgradeRun

Procedure POST /tiyi.v1.SystemService/CancelUpgradeRun
Kind unary
Auth (system:update:apply)

Request — tiyi.v1.CancelUpgradeRunRequest

Field	JSON key	Type	Cardinality	Description
`run_id`	`runId`	`string`	singular	—

Response — tiyi.v1.CancelUpgradeRunResponse

Field	JSON key	Type	Cardinality	Description
`run`	`run`	`UpgradeRun`	singular	—

SystemService.CheckForUpdates

Procedure POST /tiyi.v1.SystemService/CheckForUpdates
Kind unary
Auth (system:update:read)

Request — tiyi.v1.CheckForUpdatesRequest

Field	JSON key	Type	Cardinality	Description
`channel`	`channel`	`string`	singular	—

Response — tiyi.v1.CheckForUpdatesResponse

Field	JSON key	Type	Cardinality	Description
`releases`	`releases`	`BinaryRelease`	repeated	—
`crs_rulesets`	`crsRulesets`	`CrsRuleset`	repeated	—
`status`	`status`	`string`	singular	unconfigured, no_release, current, available
`checked_at`	`checkedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`channel`	`channel`	`string`	singular	—

SystemService.ListUpstreamCrsReleases

Procedure POST /tiyi.v1.SystemService/ListUpstreamCrsReleases
Kind unary
Auth (system:update:read)

Request — tiyi.v1.ListUpstreamCrsReleasesRequest

Field	JSON key	Type	Cardinality	Description
`limit`	`limit`	`int32`	singular	Maximum number of releases to return (default 20, max 100).
`include_prerelease`	`includePrerelease`	`bool`	singular	If true, include pre-release and draft releases.

Response — tiyi.v1.ListUpstreamCrsReleasesResponse

Field	JSON key	Type	Cardinality	Description
`releases`	`releases`	`UpstreamCrsRelease`	repeated	—

SystemService.GetObservationPipelineStats

Procedure POST /tiyi.v1.SystemService/GetObservationPipelineStats
Kind unary
Auth (system:read)

Request — tiyi.v1.GetObservationPipelineStatsRequest

No fields — send {}.

Response — tiyi.v1.GetObservationPipelineStatsResponse

Field	JSON key	Type	Cardinality	Description
`stats`	`stats`	`ObservationPipelineStats`	singular	—

SystemService.ListGeoDatabases

DB-IP Lite geo-IP datasets (country/city/asn). See internal/controlplane/geofetch. Each RPC is per (tenant, kind); a deployment typically installs at least the Country DB to enrich logs with geographic context. Enforcement IP lists accept only literal IP addresses and CIDR prefixes.

Procedure POST /tiyi.v1.SystemService/ListGeoDatabases
Kind unary
Auth (system:update:read)

Request — tiyi.v1.ListGeoDatabasesRequest

No fields — send {}.

Response — tiyi.v1.ListGeoDatabasesResponse

Field	JSON key	Type	Cardinality	Description
`items`	`items`	`GeoDatabase`	repeated	—

SystemService.DownloadGeoDatabase

Procedure POST /tiyi.v1.SystemService/DownloadGeoDatabase
Kind unary
Auth (system:update:write)

Request — tiyi.v1.DownloadGeoDatabaseRequest

Field	JSON key	Type	Cardinality	Description
`kind`	`kind`	`string`	singular	country \| city \| asn
`month`	`month`	`string`	singular	Optional YYYY-MM override. Empty → current month then previous.

Response — tiyi.v1.DownloadGeoDatabaseResponse

Field	JSON key	Type	Cardinality	Description
`database`	`database`	`GeoDatabase`	singular	—

SystemService.UploadGeoDatabase

Procedure POST /tiyi.v1.SystemService/UploadGeoDatabase
Kind unary
Auth (system:update:write)

Request — tiyi.v1.UploadGeoDatabaseRequest

Field	JSON key	Type	Cardinality	Description
`kind`	`kind`	`string`	singular	country \| city \| asn
`version`	`version`	`string`	singular	Operator-supplied label for the UI (e.g. "2026-05-custom"); if empty the server derives one from the MMDB build timestamp.
`payload`	`payload`	`bytes`	singular	Raw .mmdb or .mmdb.gz bytes. The fetcher transparently handles either. base64-encoded JSON string.

Response — tiyi.v1.UploadGeoDatabaseResponse

Field	JSON key	Type	Cardinality	Description
`database`	`database`	`GeoDatabase`	singular	—

SystemService.DeleteGeoDatabase

Procedure POST /tiyi.v1.SystemService/DeleteGeoDatabase
Kind unary
Auth (system:update:write)

Request — tiyi.v1.DeleteGeoDatabaseRequest

Field	JSON key	Type	Cardinality	Description
`kind`	`kind`	`string`	singular	—

Response — tiyi.v1.DeleteGeoDatabaseResponse

Field	JSON key	Type	Cardinality	Description
`result`	`result`	`MutationResult`	singular	—

Messages

ApplyChange

Field	JSON key	Type	Cardinality	Description
`kind`	`kind`	`string`	singular	—
`name`	`name`	`string`	singular	—
`action`	`action`	`string`	singular	—
`diff`	`diff`	`JsonPatch`	singular	—

ApplyPlan

Field	JSON key	Type	Cardinality	Description
`changes`	`changes`	`ApplyChange`	repeated	—
`warnings`	`warnings`	`string`	repeated	—

AttackDistributionItem

Field	JSON key	Type	Cardinality	Description
`tag`	`tag`	`string`	singular	—
`count`	`count`	`int64`	singular	JSON string (64-bit ints are quoted).

BinaryRelease

Field	JSON key	Type	Cardinality	Description
`id`	`id`	`string`	singular	—
`version`	`version`	`string`	singular	—
`channel`	`channel`	`string`	singular	—
`sha256`	`sha256`	`string`	singular	—
`signature`	`signature`	`string`	singular	—
`imported_at`	`importedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.

DashboardFreshness

Field	JSON key	Type	Cardinality	Description
`as_of`	`asOf`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`resolution_seconds`	`resolutionSeconds`	`int64`	singular	JSON string (64-bit ints are quoted).
`stale`	`stale`	`bool`	singular	—
`source`	`source`	`string`	singular	—
`snapshot_age_ms`	`snapshotAgeMs`	`int64`	singular	Age of the complete cached Overview response. JSON string (64-bit ints are quoted).
`snapshot_stale`	`snapshotStale`	`bool`	singular	—
`observation_degraded`	`observationDegraded`	`bool`	singular	The security observation lane sampled events under recent pressure. Exact counters and rankings are unaffected; Event Analysis and drill-down logs are based on retained samples.
`observation_dropped`	`observationDropped`	`uint64`	singular	Process-lifetime count of sampled audit log records after full counters. JSON string (64-bit ints are quoted).
`observation_last_drop_at`	`observationLastDropAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`waf_overload_state`	`wafOverloadState`	`string`	singular	Live node-local WAF pressure chain: resource pressure, Coraza causality, and the action currently selected by the overload controller.
`waf_agent_cpu_percent`	`wafAgentCpuPercent`	`double`	singular	—
`waf_coraza_demand_percent`	`wafCorazaDemandPercent`	`double`	singular	—
`waf_phase_p99_millis`	`wafPhaseP99Millis`	`int64`	singular	JSON string (64-bit ints are quoted).
`waf_overload_action`	`wafOverloadAction`	`string`	singular	—
`waf_probe_percent`	`wafProbePercent`	`int32`	singular	—
`waf_overload_last_transition_at`	`wafOverloadLastTransitionAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`waf_overload_node_id`	`wafOverloadNodeId`	`string`	singular	Worst currently affected node selected from the existing local/Agent health projections. active_nodes counts degraded + recovering nodes.
`waf_overload_node_name`	`wafOverloadNodeName`	`string`	singular	—
`waf_overload_active_nodes`	`wafOverloadActiveNodes`	`int32`	singular	—
`remote_observation_coverage`	`remoteObservationCoverage`	`ObservationCoverage`	singular	Current remote delivery state. Dashboard totals remain available but are explicitly lower bounds while any fresh online Agent reports a gap.

DashboardSecurityTopK

Field	JSON key	Type	Cardinality	Description
`items`	`items`	`DashboardSecurityTopKItem`	repeated	—
`other_count`	`otherCount`	`int64`	singular	JSON string (64-bit ints are quoted).
`total_weight`	`totalWeight`	`int64`	singular	JSON string (64-bit ints are quoted).
`unavailable_reason`	`unavailableReason`	`string`	singular	—

DashboardSecurityTopKItem

Field	JSON key	Type	Cardinality	Description
`key`	`key`	`string`	singular	—
`count`	`count`	`int64`	singular	JSON string (64-bit ints are quoted).
`geo`	`geo`	`NetworkGeo`	singular	Populated only for source-IP dimensions when GeoIP data is available.

DashboardStats

Field	JSON key	Type	Cardinality	Description
`sites_enabled`	`sitesEnabled`	`int32`	singular	—
`log_mode_degraded_sites`	`logModeDegradedSites`	`int32`	singular	—
`certs_expiring_14d`	`certsExpiring14d`	`int32`	singular	ACME / certificate renewal observability (Phase D). All counters are tenant-scoped and do not include soft-deleted rows.
`certs_expiring_30d`	`certsExpiring30d`	`int32`	singular	—
`acme_renewals_failed_24h`	`acmeRenewalsFailed24h`	`int32`	singular	—
`acme_orders_pending`	`acmeOrdersPending`	`int32`	singular	—
`acme_last_valid_at`	`acmeLastValidAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`nodes_online`	`nodesOnline`	`int32`	singular	Role-free node counts: the built-in local data plane plus enrolled remote Agents. A healthy single-node deployment reports 1 / 1.
`nodes_total`	`nodesTotal`	`int32`	singular	—

DashboardTopK

Field	JSON key	Type	Cardinality	Description
`items`	`items`	`DashboardTopKItem`	repeated	—
`other_total`	`otherTotal`	`int64`	singular	JSON string (64-bit ints are quoted).
`other_blocked`	`otherBlocked`	`int64`	singular	JSON string (64-bit ints are quoted).

DashboardTopKItem

Field	JSON key	Type	Cardinality	Description
`key`	`key`	`string`	singular	—
`total`	`total`	`int64`	singular	JSON string (64-bit ints are quoted).
`blocked`	`blocked`	`int64`	singular	JSON string (64-bit ints are quoted).

DashboardTopSite

Field	JSON key	Type	Cardinality	Description
`site_id`	`siteId`	`string`	singular	—
`total`	`total`	`int64`	singular	JSON string (64-bit ints are quoted).
`blocked`	`blocked`	`int64`	singular	JSON string (64-bit ints are quoted).

DashboardTrafficQuality

Exact request-quality totals over the same time/site scope as Overview. Rates are intentionally calculated by clients so zero-total semantics stay explicit and the wire values remain lossless integer counters.

Field	JSON key	Type	Cardinality	Description
`total`	`total`	`int64`	singular	JSON string (64-bit ints are quoted).
`status_2xx`	`status2xx`	`int64`	singular	JSON string (64-bit ints are quoted).
`status_3xx`	`status3xx`	`int64`	singular	JSON string (64-bit ints are quoted).
`status_4xx`	`status4xx`	`int64`	singular	JSON string (64-bit ints are quoted).
`status_5xx`	`status5xx`	`int64`	singular	JSON string (64-bit ints are quoted).
`slow_requests`	`slowRequests`	`int64`	singular	JSON string (64-bit ints are quoted).
`gateway_errors`	`gatewayErrors`	`int64`	singular	JSON string (64-bit ints are quoted).
`duration_sum_micros`	`durationSumMicros`	`int64`	singular	JSON string (64-bit ints are quoted).
`business_requests`	`businessRequests`	`int64`	singular	Requests that were not terminated by a trusted Tiyi enforcement action. Dashboard quality rates use this denominator so protection traffic does not dilute application availability or latency. JSON string (64-bit ints are quoted).
`business_status_4xx`	`businessStatus4xx`	`int64`	singular	JSON string (64-bit ints are quoted).
`business_status_5xx`	`businessStatus5xx`	`int64`	singular	JSON string (64-bit ints are quoted).
`business_slow_requests`	`businessSlowRequests`	`int64`	singular	JSON string (64-bit ints are quoted).
`business_very_slow_requests`	`businessVerySlowRequests`	`int64`	singular	JSON string (64-bit ints are quoted).
`business_duration_sum_micros`	`businessDurationSumMicros`	`int64`	singular	JSON string (64-bit ints are quoted).
`top_business_4xx_status`	`topBusiness4xxStatus`	`int32`	singular	—
`top_business_4xx_count`	`topBusiness4xxCount`	`int64`	singular	JSON string (64-bit ints are quoted).
`top_business_5xx_status`	`topBusiness5xxStatus`	`int32`	singular	—
`top_business_5xx_count`	`topBusiness5xxCount`	`int64`	singular	JSON string (64-bit ints are quoted).

GeoDatabase

GeoDatabase is the metadata projection the UI consumes (no blob). Kind is "country", "city", or "asn". License: DB-IP Lite is CC-BY-4.0, the UI surfaces the attribution whenever the table is populated.

Field	JSON key	Type	Cardinality	Description
`kind`	`kind`	`string`	singular	—
`version`	`version`	`string`	singular	—
`source`	`source`	`string`	singular	online \| offline
`sha256`	`sha256`	`string`	singular	—
`size_bytes`	`sizeBytes`	`int64`	singular	JSON string (64-bit ints are quoted).
`build_epoch`	`buildEpoch`	`int64`	singular	MMDB build timestamp (unix seconds) JSON string (64-bit ints are quoted).
`node_count`	`nodeCount`	`int64`	singular	JSON string (64-bit ints are quoted).
`fetched_at`	`fetchedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`created_at`	`createdAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`updated_at`	`updatedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`activation_status`	`activationStatus`	`string`	singular	Country only: pending \| activating \| active \| failed. City/ASN report not_applicable. A failed state is retried independently of auto-download.
`activated_sha256`	`activatedSha256`	`string`	singular	—
`last_activation_error`	`lastActivationError`	`string`	singular	—
`activation_attempted_at`	`activationAttemptedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`activated_at`	`activatedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.

LicenseStatus

LicenseStatus is the scale-gate status surfaced on the About page (docs/design/licensing-scale-gate.md § 3.7). No new service or page: it rides on the existing SystemService.Version response.

Field	JSON key	Type	Cardinality	Description
`edition`	`edition`	`string`	singular	"Community (single node)" or, in Phase 2, the plan.
`remote_nodes`	`remoteNodes`	`int32`	singular	deployment-wide live remote-agent count.
`max_remote_nodes`	`maxRemoteNodes`	`int32`	singular	node budget; 0 for unlicensed Community.
`licensee`	`licensee`	`string`	singular	Signed-license display fields. Empty/unset for unlicensed Community.
`expires_at`	`expiresAt`	`google.protobuf.Timestamp`	singular	license expiry; unset = perpetual. RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`source`	`source`	`string`	singular	built_in, stored, file
`import_supported`	`importSupported`	`bool`	singular	—
`status`	`status`	`string`	singular	community, valid, expired, invalid
`error`	`error`	`string`	singular	—

ObservationLaneStats

Field	JSON key	Type	Cardinality	Description
`name`	`name`	`string`	singular	—
`attempted`	`attempted`	`uint64`	singular	JSON string (64-bit ints are quoted).
`admitted`	`admitted`	`uint64`	singular	JSON string (64-bit ints are quoted).
`written`	`written`	`uint64`	singular	JSON string (64-bit ints are quoted).
`dropped`	`dropped`	`uint64`	singular	JSON string (64-bit ints are quoted).
`retried`	`retried`	`uint64`	singular	JSON string (64-bit ints are quoted).
`panicked`	`panicked`	`uint64`	singular	JSON string (64-bit ints are quoted).
`pending_items`	`pendingItems`	`int64`	singular	JSON string (64-bit ints are quoted).
`pending_bytes`	`pendingBytes`	`int64`	singular	JSON string (64-bit ints are quoted).
`capacity`	`capacity`	`int64`	optional (explicit)	JSON string (64-bit ints are quoted).
`last_error`	`lastError`	`string`	singular	—
`last_error_at`	`lastErrorAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`sampled`	`sampled`	`uint64`	singular	Intentionally shed before admission to protect the request path. This is degraded sampling coverage, not an unexpected post-admission loss. JSON string (64-bit ints are quoted).
`sampled_client_limit`	`sampledClientLimit`	`uint64`	singular	Repeats collapsed by the per-client fairness budget. JSON string (64-bit ints are quoted).
`sampled_global_budget`	`sampledGlobalBudget`	`uint64`	singular	Shed because the node-wide coverage/repeat budget was exhausted. JSON string (64-bit ints are quoted).
`sampled_queue_pressure`	`sampledQueuePressure`	`uint64`	singular	Shed because reserved queue items or bytes were exhausted. JSON string (64-bit ints are quoted).
`byte_capacity`	`byteCapacity`	`int64`	optional (explicit)	JSON string (64-bit ints are quoted).
`last_success_at`	`lastSuccessAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`display_name`	`displayName`	`string`	singular	—
`state`	`state`	`string`	singular	ready, disabled or unavailable; lifetime counters remain independent.

ObservationPipelineStats

Field	JSON key	Type	Cardinality	Description
`lanes`	`lanes`	`ObservationLaneStats`	repeated	—
`panicked_total`	`panickedTotal`	`uint64`	singular	JSON string (64-bit ints are quoted).
`boundary_panics`	`boundaryPanics`	`uint64`	singular	JSON string (64-bit ints are quoted).
`invalid_envelopes`	`invalidEnvelopes`	`uint64`	singular	JSON string (64-bit ints are quoted).
`late_detail_beyond_retention`	`lateDetailBeyondRetention`	`uint64`	singular	JSON string (64-bit ints are quoted).
`data_plane_requests`	`dataPlaneRequests`	`uint64`	singular	JSON string (64-bit ints are quoted).
`data_plane_blocked`	`dataPlaneBlocked`	`uint64`	singular	JSON string (64-bit ints are quoted).
`active_connections`	`activeConnections`	`int64`	singular	JSON string (64-bit ints are quoted).
`late_metric_beyond_retention`	`lateMetricBeyondRetention`	`uint64`	singular	JSON string (64-bit ints are quoted).
`available`	`available`	`bool`	singular	—
`epoch`	`epoch`	`string`	singular	—
`started_at`	`startedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`observed_at`	`observedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`siem_delivery_losses`	`siemDeliveryLosses`	`uint64`	singular	JSON string (64-bit ints are quoted).

SystemHealthCheck

Independent current component observation. status is healthy, unhealthy or unknown.

Field	JSON key	Type	Cardinality	Description
`component`	`component`	`string`	singular	—
`status`	`status`	`string`	singular	—
`message`	`message`	`string`	singular	—
`checked_at`	`checkedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`duration_ms`	`durationMs`	`int64`	singular	JSON string (64-bit ints are quoted).

SystemSettings

Field	JSON key	Type	Cardinality	Description
`id`	`id`	`string`	singular	—
`values`	`values`	`google.protobuf.Struct`	singular	free-form JSON object.
`updated_at`	`updatedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`sources`	`sources`	map<`string`, `string`>	map	—

TopAttacker

Field	JSON key	Type	Cardinality	Description
`client_ip`	`clientIp`	`string`	singular	—
`count`	`count`	`int64`	singular	JSON string (64-bit ints are quoted).
`top_tags`	`topTags`	`string`	repeated	—
`geo`	`geo`	`NetworkGeo`	singular	Best-effort source-network context; absent when GeoIP cannot resolve it.

TrafficPoint

Field	JSON key	Type	Cardinality	Description
`bucket_start`	`bucketStart`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`total`	`total`	`int64`	singular	JSON string (64-bit ints are quoted).
`blocked`	`blocked`	`int64`	singular	JSON string (64-bit ints are quoted).
`bytes_in`	`bytesIn`	`int64`	singular	Exact HTTP payload bytes for this bucket. bytes_in is request-body data read from clients; bytes_out is response-body data written to clients. Headers, TLS and transport framing are intentionally excluded. JSON string (64-bit ints are quoted).
`bytes_out`	`bytesOut`	`int64`	singular	JSON string (64-bit ints are quoted).
`interval_seconds`	`intervalSeconds`	`int64`	singular	Effective wall-clock coverage of this bucket. The first and last buckets may be partial when the requested range is not bucket-aligned. JSON string (64-bit ints are quoted).

UpgradeRun

Field	JSON key	Type	Cardinality	Description
`id`	`id`	`string`	singular	—
`target_version`	`targetVersion`	`string`	singular	—
`status`	`status`	`UpgradeRunStatus`	singular	—
`started_at`	`startedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`finished_at`	`finishedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.

UpgradeRunEvent

Field	JSON key	Type	Cardinality	Description
`run_id`	`runId`	`string`	singular	—
`kind`	`kind`	`UpgradeRunEventKind`	singular	—
`occurred_at`	`occurredAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`payload`	`payload`	`google.protobuf.Struct`	singular	free-form JSON object.

UpstreamCrsRelease

Field	JSON key	Type	Cardinality	Description
`tag`	`tag`	`string`	singular	—
`name`	`name`	`string`	singular	—
`published_at`	`publishedAt`	`google.protobuf.Timestamp`	singular	RFC 3339 string, e.g. `2026-07-26T09:00:00Z`.
`tarball_url`	`tarballUrl`	`string`	singular	—
`prerelease`	`prerelease`	`bool`	singular	—
`draft`	`draft`	`bool`	singular	—
`body`	`body`	`string`	singular	—

Enums

UpgradeRunEventKind

Value	Number	Description
`UPGRADE_RUN_EVENT_KIND_UNSPECIFIED`	0	—
`UPGRADE_RUN_EVENT_KIND_WAVE_STARTED`	1	—
`UPGRADE_RUN_EVENT_KIND_NODE_UPDATED`	2	—
`UPGRADE_RUN_EVENT_KIND_NODE_FAILED`	3	—
`UPGRADE_RUN_EVENT_KIND_WAVE_COMPLETED`	4	—
`UPGRADE_RUN_EVENT_KIND_RUN_SUCCEEDED`	5	—
`UPGRADE_RUN_EVENT_KIND_RUN_FAILED`	6	—
`UPGRADE_RUN_EVENT_KIND_RUN_CANCELED`	7	—

UpgradeRunStatus

Value	Number	Description
`UPGRADE_RUN_STATUS_UNSPECIFIED`	0	—
`UPGRADE_RUN_STATUS_PENDING`	1	—
`UPGRADE_RUN_STATUS_RUNNING`	2	—
`UPGRADE_RUN_STATUS_SUCCEEDED`	3	—
`UPGRADE_RUN_STATUS_FAILED`	4	—
`UPGRADE_RUN_STATUS_CANCELED`	5	—