{
"properties": {
"id": {
"description": "Unique identifier of the BYOC infrastructure",
"type": "string"
},
"state": {
"description": "State of the infrastructure",
"type": "string",
"enum": [
"infra-provisioning",
"infra-terminated",
"infra-terminating",
"infra-ready",
"infra-degraded",
"infra-upgrading"
],
"example": "infra-ready"
},
"accountId": {
"description": "Cloud account ID the BYOC infrastructure is bound to: AWS account ID, GCP project ID, or Azure subscription ID",
"type": "string",
"example": "123456789012"
},
"regionId": {
"description": "Region the BYOC infrastructure is located in",
"type": "string",
"enum": [
"ap-northeast-1",
"ap-northeast-2",
"ap-south-1",
"ap-southeast-1",
"ap-southeast-2",
"ca-central-1",
"eu-central-1",
"eu-west-1",
"eu-west-2",
"il-central-1",
"us-east-1",
"us-east-2",
"us-west-2",
"us-east1",
"us-central1",
"europe-west2",
"europe-west4",
"asia-southeast1",
"asia-northeast1",
"eastus",
"eastus2",
"westus3",
"germanywestcentral",
"centralus"
]
},
"cloudProvider": {
"description": "Cloud provider of the region",
"type": "string",
"enum": [
"gcp",
"aws",
"azure"
]
},
"displayName": {
"description": "Human readable name for infrastructure",
"type": "string"
},
"enablePrivateLink": {
"description": "Whether private link connectivity is enabled on the infrastructure",
"type": "boolean"
},
"enablePrivateLoadBalancer": {
"description": "Whether the private load balancer is enabled on the infrastructure",
"type": "boolean"
},
"enablePublicLoadBalancer": {
"description": "Whether the public load balancer is enabled on the infrastructure",
"type": "boolean"
},
"vpcCidrRange": {
"description": "CIDR range of the ClickHouse-managed VPC. Absent for BYO-VPC infrastructures",
"type": "string",
"example": "10.0.0.0/16"
},
"vpcAvailabilityZoneList": {
"type": "array",
"description": "Availability zones the infrastructure spans",
"items": {
"type": "string"
},
"example": [
"us-east-1a",
"us-east-1b",
"us-east-1c"
]
},
"isByoVpc": {
"description": "True when the infrastructure runs in a customer-provided VPC (BYO-VPC) instead of a ClickHouse-managed one",
"type": "boolean"
},
"byoVpcId": {
"description": "Customer VPC ID or network name (BYO-VPC only)",
"type": "string",
"example": "vpc-0abc1234def567890"
},
"byoVpcPrivateSubnetIds": {
"type": "array",
"description": "Customer private subnet IDs or names (BYO-VPC only; exactly one entry on GCP)",
"items": {
"type": "string"
}
},
"byoVpcPodCidrRangeNames": {
"type": "array",
"description": "Secondary IP range names pinned for pod IPs (GCP BYO-VPC only). Absent when all secondary ranges are used",
"items": {
"type": "string"
}
},
"byoVpcSharedVpcHostProjectId": {
"description": "Shared VPC host project owning the VPC and subnet (GCP BYO-VPC only). Absent when the VPC lives in the service project",
"type": "string"
},
"gcpPscSubnetId": {
"description": "Customer-provided Private Service Connect NAT subnet name configured for private link (GCP BYO-VPC only)",
"type": "string"
}
}
}
The live ClickHouse Cloud OpenAPI spec has drifted from the Rust API library.
The comparison was produced by the shared
syn-based analyzer.https://api.clickhouse.cloud/v1crates/clickhouse-cloud-api/src/client.rscrates/clickhouse-cloud-api/src/models.rscrates/clickhouse-openapi-analyzerSummary
Missing Client Methods
organization_byoc_infrastructure_getGET
/v1/organizations/{organizationId}/byocInfrastructure/{byocInfrastructureId}Operation spec JSON
{ "summary": "Get BYOC infrastructure details", "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future. <br /><br /> Returns the full configuration of a BYOC infrastructure, including private link and load balancer state, network layout, and BYO-VPC settings read from the data plane.", "operationId": "organizationByocInfrastructureGet", "parameters": [ { "in": "path", "name": "organizationId", "description": "ID of the requested organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "byocInfrastructureId", "description": "ID of the requested BYOC Infrastructure", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "HTTP status code.", "example": 200 }, "requestId": { "type": "string", "description": "Unique id assigned to every request. UUIDv4", "format": "uuid" }, "result": { "$ref": "#/components/schemas/ByocInfrastructureDetails" } } } } } }, "400": { "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "HTTP status code.", "example": 400 }, "error": { "type": "string", "description": "Detailed error description." }, "requestId": { "type": "string", "description": "Unique id assigned to every request. UUIDv4", "format": "uuid" } } } } } }, "500": { "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code.", "example": 500 }, "error": { "type": "string", "description": "Detailed error description." }, "requestId": { "type": "string", "description": "Unique id assigned to every request. UUIDv4", "format": "uuid" } } } } } } }, "security": [ { "basicAuth": [ "control-plane:organization:view" ] } ], "tags": [ "Organization" ], "x-badges": [ { "name": "Beta", "position": "after" } ] }organization_byoc_infrastructure_progress_getGET
/v1/organizations/{organizationId}/byocInfrastructure/{byocInfrastructureId}/progressOperation spec JSON
{ "summary": "Get BYOC infrastructure provisioning progress", "description": "**Disclaimer:** This beta endpoint is evolving; the API contract may change. <br /><br /> Returns the stage-by-stage provisioning progress of a BYOC infrastructure, more granular than the `state` field: overall status plus a tree of provisioning stages down to individual cloud resources.", "operationId": "organizationByocInfrastructureProgressGet", "parameters": [ { "in": "path", "name": "organizationId", "description": "ID of the requested organization.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "byocInfrastructureId", "description": "ID of the requested BYOC Infrastructure", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "HTTP status code.", "example": 200 }, "requestId": { "type": "string", "description": "Unique id assigned to every request. UUIDv4", "format": "uuid" }, "result": { "$ref": "#/components/schemas/ByocInfrastructureProgress" } } } } } }, "400": { "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "number", "description": "HTTP status code.", "example": 400 }, "error": { "type": "string", "description": "Detailed error description." }, "requestId": { "type": "string", "description": "Unique id assigned to every request. UUIDv4", "format": "uuid" } } } } } }, "500": { "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code.", "example": 500 }, "error": { "type": "string", "description": "Detailed error description." }, "requestId": { "type": "string", "description": "Unique id assigned to every request. UUIDv4", "format": "uuid" } } } } } } }, "security": [ { "basicAuth": [ "control-plane:organization:view" ] } ], "tags": [ "Organization" ], "x-badges": [ { "name": "Beta", "position": "after" } ] }Missing Struct Fields
/components/schemas/ByocConfig/properties/accountId— ByocConfig.accountId is missing from models.rs/components/schemas/ClickPipeKafkaSource/properties/tombstoneMode— ClickPipeKafkaSource.tombstoneMode is missing from models.rs/components/schemas/ClickPipeKinesisSource/properties/schemaRegistry— ClickPipeKinesisSource.schemaRegistry is missing from models.rs/components/schemas/ClickPipePostKafkaSource/properties/tombstoneMode— ClickPipePostKafkaSource.tombstoneMode is missing from models.rs/components/schemas/ClickPipePostKinesisSource/properties/schemaRegistry— ClickPipePostKinesisSource.schemaRegistry is missing from models.rs/components/schemas/Organization/properties/capabilities— Organization.capabilities is missing from models.rsMissing Enum Values
/components/schemas/Activity/properties/type— ActivityType has no variant for wire value "organization_approved_domain_auto_invite"/components/schemas/Activity/properties/type— ActivityType has no variant for wire value "organization_approved_domain_auto_join"/components/schemas/Activity/properties/type— ActivityType has no variant for wire value "organization_approved_domain_delete"/components/schemas/Activity/properties/type— ActivityType has no variant for wire value "organization_approved_domain_update"/components/schemas/Activity/properties/type— ActivityType has no variant for wire value "organization_approved_domain_verify"/components/schemas/Activity/properties/type— ActivityType has no variant for wire value "organization_update_public_preview"/components/schemas/Activity/properties/type— ActivityType has no variant for wire value "organization_update_saml_query_ownership_migration"/components/schemas/ByocConfig/properties/state— ByocConfigState has no variant for wire value "infra-degraded"/components/schemas/ByocConfig/properties/state— ByocConfigState has no variant for wire value "infra-terminating"/components/schemas/ByocConfig/properties/state— ByocConfigState has no variant for wire value "infra-upgrading"Newly Beta Operations
/paths/~1v1~1organizations~1{organizationId}~1byocInfrastructure~1{byocInfrastructureId}/get— organization_byoc_infrastructure_get is Beta in the spec but absent from BETA_OPERATIONS/paths/~1v1~1organizations~1{organizationId}~1byocInfrastructure~1{byocInfrastructureId}~1progress/get— organization_byoc_infrastructure_progress_get is Beta in the spec but absent from BETA_OPERATIONSNewly Deprecated Fields
/components/schemas/ByocConfig/properties/accountName— ByocConfig.accountName is deprecated in the spec but absent from DEPRECATED_FIELDSNew Operations Missing From Snapshot
/paths/~1v1~1organizations~1{organizationId}~1byocInfrastructure~1{byocInfrastructureId}/get— operation organization_byoc_infrastructure_get is present in the target spec but absent from the snapshot/paths/~1v1~1organizations~1{organizationId}~1byocInfrastructure~1{byocInfrastructureId}~1progress/get— operation organization_byoc_infrastructure_progress_get is present in the target spec but absent from the snapshotNew Schemas Missing From Snapshot
/components/schemas/ByocInfrastructureDetails— schema ByocInfrastructureDetails is present in the target spec but absent from the snapshot/components/schemas/ByocInfrastructureProgress— schema ByocInfrastructureProgress is present in the target spec but absent from the snapshot/components/schemas/ByocInfrastructureProgressStage— schema ByocInfrastructureProgressStage is present in the target spec but absent from the snapshot/components/schemas/ClickPipeKinesisSchemaRegistry— schema ClickPipeKinesisSchemaRegistry is present in the target spec but absent from the snapshot/components/schemas/OrganizationCapabilities— schema OrganizationCapabilities is present in the target spec but absent from the snapshotMissing Model Types
ByocInfrastructureDetails(spec:ByocInfrastructureDetails)Schema JSON
{ "properties": { "id": { "description": "Unique identifier of the BYOC infrastructure", "type": "string" }, "state": { "description": "State of the infrastructure", "type": "string", "enum": [ "infra-provisioning", "infra-terminated", "infra-terminating", "infra-ready", "infra-degraded", "infra-upgrading" ], "example": "infra-ready" }, "accountId": { "description": "Cloud account ID the BYOC infrastructure is bound to: AWS account ID, GCP project ID, or Azure subscription ID", "type": "string", "example": "123456789012" }, "regionId": { "description": "Region the BYOC infrastructure is located in", "type": "string", "enum": [ "ap-northeast-1", "ap-northeast-2", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ca-central-1", "eu-central-1", "eu-west-1", "eu-west-2", "il-central-1", "us-east-1", "us-east-2", "us-west-2", "us-east1", "us-central1", "europe-west2", "europe-west4", "asia-southeast1", "asia-northeast1", "eastus", "eastus2", "westus3", "germanywestcentral", "centralus" ] }, "cloudProvider": { "description": "Cloud provider of the region", "type": "string", "enum": [ "gcp", "aws", "azure" ] }, "displayName": { "description": "Human readable name for infrastructure", "type": "string" }, "enablePrivateLink": { "description": "Whether private link connectivity is enabled on the infrastructure", "type": "boolean" }, "enablePrivateLoadBalancer": { "description": "Whether the private load balancer is enabled on the infrastructure", "type": "boolean" }, "enablePublicLoadBalancer": { "description": "Whether the public load balancer is enabled on the infrastructure", "type": "boolean" }, "vpcCidrRange": { "description": "CIDR range of the ClickHouse-managed VPC. Absent for BYO-VPC infrastructures", "type": "string", "example": "10.0.0.0/16" }, "vpcAvailabilityZoneList": { "type": "array", "description": "Availability zones the infrastructure spans", "items": { "type": "string" }, "example": [ "us-east-1a", "us-east-1b", "us-east-1c" ] }, "isByoVpc": { "description": "True when the infrastructure runs in a customer-provided VPC (BYO-VPC) instead of a ClickHouse-managed one", "type": "boolean" }, "byoVpcId": { "description": "Customer VPC ID or network name (BYO-VPC only)", "type": "string", "example": "vpc-0abc1234def567890" }, "byoVpcPrivateSubnetIds": { "type": "array", "description": "Customer private subnet IDs or names (BYO-VPC only; exactly one entry on GCP)", "items": { "type": "string" } }, "byoVpcPodCidrRangeNames": { "type": "array", "description": "Secondary IP range names pinned for pod IPs (GCP BYO-VPC only). Absent when all secondary ranges are used", "items": { "type": "string" } }, "byoVpcSharedVpcHostProjectId": { "description": "Shared VPC host project owning the VPC and subnet (GCP BYO-VPC only). Absent when the VPC lives in the service project", "type": "string" }, "gcpPscSubnetId": { "description": "Customer-provided Private Service Connect NAT subnet name configured for private link (GCP BYO-VPC only)", "type": "string" } } }ByocInfrastructureProgress(spec:ByocInfrastructureProgress)Schema JSON
{ "properties": { "id": { "description": "Unique identifier of the BYOC infrastructure", "type": "string" }, "status": { "description": "Overall provisioning status of the infrastructure", "type": "string", "enum": [ "not_started", "pending", "waiting", "in_progress", "ready", "failed" ], "example": "in_progress" }, "updatedAt": { "description": "Timestamp the overall status last changed. ISO-8601", "type": "string", "format": "date-time" }, "stages": { "type": "array", "description": "Top-level provisioning stages with their nested resources", "items": { "$ref": "#/components/schemas/ByocInfrastructureProgressStage" } } } }ByocInfrastructureProgressStage(spec:ByocInfrastructureProgressStage)Schema JSON
{ "properties": { "name": { "description": "Name of the provisioning stage or resource", "type": "string", "example": "vpc" }, "status": { "description": "Status of this stage", "type": "string", "enum": [ "not_started", "pending", "waiting", "in_progress", "ready", "failed" ], "example": "ready" }, "updatedAt": { "description": "Timestamp the stage status last changed. ISO-8601", "type": "string", "format": "date-time" }, "message": { "description": "Human readable detail for the current status, e.g. an error message", "type": "string" }, "subStages": { "type": "array", "description": "Nested stages; leaf entries are individual cloud resources", "items": { "$ref": "#/components/schemas/ByocInfrastructureProgressStage" } } } }ClickPipeKinesisSchemaRegistry(spec:ClickPipeKinesisSchemaRegistry)Schema JSON
{ "properties": { "type": { "description": "Type of the schema registry. Kinesis ClickPipes support the AWS Glue Schema Registry, which authenticates with IAM instead of credentials.", "type": "string", "enum": [ "glue" ] }, "glueRegion": { "description": "AWS region of the Glue Schema Registry.", "type": "string", "example": "us-east-1" }, "glueRegistryName": { "description": "Name of the Glue Schema Registry.", "type": "string", "example": "my-registry" }, "glueRoleArn": { "description": "IAM role to assume for Glue Schema Registry access. Defaults to the IAM identity of the Kinesis source.", "type": [ "string", "null" ], "example": "arn:aws:iam::123456789012:role/MyGlueRegistryRole" } }, "required": [ "type", "glueRegion", "glueRegistryName" ] }OrganizationCapabilities(spec:OrganizationCapabilities)Schema JSON
{ "properties": { "snapshots": { "description": "Whether the organization is eligible to use service snapshots: true only when the organization has the snapshots feature enabled, is on a PPv2 tier, and has the backups entitlement \u2014 the same conditions enforced when a snapshotConfiguration is saved. Check this before configuring snapshots on a service. Snapshots apply to primary services only, so a secondary/replica service is rejected regardless of organization eligibility.", "type": "boolean" } } }Acknowledged Unsupported Enum Constraints
These locations are inventoried but cannot yet be compared to a typed Rust value enum.
Acknowledgments cover the snapshot's enum values; changed values and new or stale locations count as drift.
/components/schemas/ApiKey/properties/roles/items(models.rs::ApiKey::roles) — Rust type String is not an enum/components/schemas/ApiKeyPatchRequest/properties/roles/items(models.rs::ApiKeyPatchRequest::roles) — Rust type String is not an enum/components/schemas/ApiKeyPostRequest/properties/roles/items(models.rs::ApiKeyPostRequest::roles) — Rust type String is not an enumImplementation Guide
crates/clickhouse-cloud-api/clickhouse_cloud_openapi.jsonwith this same live document; do not hand-edit it.spec_pointerandrust_itemto updateclient.rs,models.rs, ormeta.rs.crates/clickhouse-openapi-analyzer/src/config.rsonly for a deliberate, documented divergence. New unsupported acknowledgements require a tracking issue.AGENTS.mdfor the exact commands.