Organizations API¶

The API host in the following examples must match your Workspace's region. See the full list of regions and hosts

Use the Organizations API to manage dedicated cluster operations.

This reference only includes cluster management endpoints.

All endpoints require authentication using a Token with the appropriate permissions.

GET /v0/organizations/(.+)/clusters/?¶

Returns detailed cluster information for an organization.

This endpoint lists dedicated clusters assigned to the organization, including replica state, traffic weights, and maintenance/version metadata used by cluster management tooling.

Listing organization clusters¶

curl -X GET \
    -H "Authorization: Bearer <user_token>" \
    "https://<your_host>/v0/organizations/<organization_id>/clusters"

Successful response¶

{
  "clusters": [
    {
      "cluster_id": "<cluster_id>",
      "cluster_name": "<cluster_name>",
      "cloud_provider": "aws",
      "cloud_region": "eu-west-1",
      "operation_in_progress": false,
      "can_rebalance": true,
      "can_scale": true,
      "cluster_weights": {
        "writer": {"replica-1": 100},
        "reader": {"replica-1": 100}
      },
      "replicas": {
        "replica-1": {
          "name": "replica-1",
          "cpu": 4,
          "memory_gb": 16,
          "state": "running"
        }
      },
      "error": null,
      "ongoing_maintenance": false,
      "clickhouse_version": "24.8",
      "available_clickhouse_versions": ["24.8", "24.12"],
      "rolling_update_config": null
    }
  ]
}

Response fields¶
Field	Type	Description
clusters	Array[Object]	List of dedicated clusters configured for the organization.
clusters[].cluster_id	String	Identifier used by management operations.
clusters[].cluster_name	String	Internal cluster name.
clusters[].cloud_provider	String	Cloud provider hosting the cluster.
clusters[].cloud_region	String	Region where the cluster is deployed.
clusters[].operation_in_progress	Boolean	Whether a cluster operation is currently running.
clusters[].can_rebalance	Boolean	Whether weights can be rebalanced at this time.
clusters[].can_scale	Boolean	Whether replicas can be scaled at this time.
clusters[].cluster_weights	Object	Current traffic distribution by role and replica.
clusters[].replicas	Object	Replica details keyed by replica name.
clusters[].error	String or null	Last cluster-level error, if any.
clusters[].ongoing_maintenance	Boolean	Whether the cluster is currently under maintenance.
clusters[].clickhouse_version	String or null	Current ClickHouse version for the cluster.
clusters[].available_clickhouse_versions	Array[String]	Supported target versions for upgrades.
clusters[].rolling_update_config	Object or null	Rolling update settings when configured.

PUT /v0/organizations/(.+)/clusters/(.+)/weights/?¶

Updates traffic weights for replicas in a dedicated cluster.

Use this endpoint to request a manual rebalance by sending the current weights and the desired new weights.

Rebalancing cluster weights¶

curl -X PUT \
    -H "Authorization: Bearer <user_token>" \
    -H "Content-Type: application/json" \
    "https://<your_host>/v0/organizations/<organization_id>/clusters/<cluster_id>/weights" \
    -d '{
        "old_weights": {
            "writer": {"replica-1": 100, "replica-2": 0},
            "reader": {"replica-1": 100, "replica-2": 0}
            },
        "new_weights": {
            "writer": {"replica-1": 50, "replica-2": 50},
            "reader": {"replica-1": 60, "replica-2": 40}
        }
    }'

Successful response¶

{
  "cluster_id": "<cluster_id>",
  "updated_weights": {
    "writer": {
      "replica-1": 50,
      "replica-2": 50
    },
    "reader": {
      "replica-1": 60,
      "replica-2": 40
    }
  },
  "operation": "weight_update_requested"
}

Request body fields¶
Field	Type	Description
old_weights	Object	Current weights by role and replica.
new_weights	Object	Target weights by role and replica.

POST /v0/organizations/(.+)/clusters/(.+)/replicas/(.+)/?¶

Adds a replica to a dedicated cluster and triggers rebalancing.

Adding a replica¶

curl -X POST \
    -H "Authorization: Bearer <user_token>" \
    -H "Content-Type: application/json" \
    "https://<your_host>/v0/organizations/<organization_id>/clusters/<cluster_id>/replicas"                 -d '{
        "replica_size": "4-16",
        "existing_replicas": {
            "old_weights": {
                "writer": {"replica-1": 100},
                "reader": {"replica-1": 100}
            },
            "new_weights": {
                "writer": {"replica-1": 70},
                "reader": {"replica-1": 80}
            }
        },
        "new_replica": {
            "writer": 30,
            "reader": 20
        }
    }'

Successful response¶

{
  "cluster_id": "<cluster_id>",
  "new_replica": {
    "name": "replica-2",
    "cpu": 4,
    "memory_gb": 16,
    "state": "adding"
  },
  "operation": "replica_add_requested"
}

Request body fields¶
Field	Type	Description
replica_size	String	Replica shape in `cpu-memory` format, for example `4-16`.
existing_replicas	Object	Current and target weights for existing replicas. Must include `old_weights` and `new_weights`.
new_replica	Object	Weights to assign to the new replica by role.

DELETE /v0/organizations/(.+)/clusters/(.+)/replicas/(.+)/?¶

Removes a replica from a dedicated cluster and rebalances traffic.

Removing a replica¶

curl -X DELETE \
    -H "Authorization: Bearer <user_token>" \
    -H "Content-Type: application/json" \
    "https://<your_host>/v0/organizations/<organization_id>/clusters/<cluster_id>/replicas/<replica_name>"                 -d '{
        "old_weights": {
            "copyjob": {"replica-1": 1, "replica-2": 1},
            "writer": {"replica-1": 70, "replica-2": 30},
            "reader": {"replica-1": 80, "replica-2": 20}
        },
        "new_weights": {
            "copyjob": {"replica-1": 1},
            "writer": {"replica-1": 100},
            "reader": {"replica-1": 100}
        }
    }'

Successful response¶

{
  "cluster_id": "<cluster_id>",
  "removed_replica": "<replica_name>",
  "updated_weights": {
    "writer": {
      "replica-1": 100
    },
    "reader": {
      "replica-1": 100
    }
  },
  "operation": "replica_delete_requested"
}

Request body fields¶
Field	Type	Description
old_weights	Object	Current weights by role and replica.
new_weights	Object	Target weights by role and replica. It must not include the removed replica.

POST /v0/organizations/(.+)/clusters/(.+)/replicas/?¶

Adds a replica to a dedicated cluster and triggers rebalancing.

Adding a replica¶

curl -X POST \
    -H "Authorization: Bearer <user_token>" \
    -H "Content-Type: application/json" \
    "https://<your_host>/v0/organizations/<organization_id>/clusters/<cluster_id>/replicas"                 -d '{
        "replica_size": "4-16",
        "existing_replicas": {
            "old_weights": {
                "writer": {"replica-1": 100},
                "reader": {"replica-1": 100}
            },
            "new_weights": {
                "writer": {"replica-1": 70},
                "reader": {"replica-1": 80}
            }
        },
        "new_replica": {
            "writer": 30,
            "reader": 20
        }
    }'

Successful response¶

{
  "cluster_id": "<cluster_id>",
  "new_replica": {
    "name": "replica-2",
    "cpu": 4,
    "memory_gb": 16,
    "state": "adding"
  },
  "operation": "replica_add_requested"
}

Request body fields¶
Field	Type	Description
replica_size	String	Replica shape in `cpu-memory` format, for example `4-16`.
existing_replicas	Object	Current and target weights for existing replicas. Must include `old_weights` and `new_weights`.
new_replica	Object	Weights to assign to the new replica by role.

DELETE /v0/organizations/(.+)/clusters/(.+)/replicas/?¶

Removes a replica from a dedicated cluster and rebalances traffic.

Removing a replica¶

curl -X DELETE \
    -H "Authorization: Bearer <user_token>" \
    -H "Content-Type: application/json" \
    "https://<your_host>/v0/organizations/<organization_id>/clusters/<cluster_id>/replicas/<replica_name>"                 -d '{
        "old_weights": {
            "copyjob": {"replica-1": 1, "replica-2": 1},
            "writer": {"replica-1": 70, "replica-2": 30},
            "reader": {"replica-1": 80, "replica-2": 20}
        },
        "new_weights": {
            "copyjob": {"replica-1": 1},
            "writer": {"replica-1": 100},
            "reader": {"replica-1": 100}
        }
    }'

Successful response¶

{
  "cluster_id": "<cluster_id>",
  "removed_replica": "<replica_name>",
  "updated_weights": {
    "writer": {
      "replica-1": 100
    },
    "reader": {
      "replica-1": 100
    }
  },
  "operation": "replica_delete_requested"
}

Request body fields¶
Field	Type	Description
old_weights	Object	Current weights by role and replica.
new_weights	Object	Target weights by role and replica. It must not include the removed replica.

GET /v0/organizations/(.+)/clusters-configuration/?¶

Returns cluster configuration metadata, including available replica sizes.

Listing available replica sizes¶

curl -X GET \
    "https://<your_host>/v0/organizations/<organization_id>/clusters-configuration?token=<user_token>"

Successful response¶

{
  "cloud_regions": {
    "aws": [
      "us-east-1",
      "us-west-2",
      "eu-central-1",
      "eu-west-1",
      "ap-east-1"
    ],
    "gcp": [
      "europe-west3",
      "us-east4",
      "europe-west2",
      "northamerica-northeast2"
    ]
  },
  "available_sizes": {
    "aws": [
      {
        "name": "4-32",
        "cpu": 4,
        "memory_gb": 32
      },
      {
        "name": "8-32",
        "cpu": 8,
        "memory_gb": 32
      },
      {
        "name": "16-64",
        "cpu": 16,
        "memory_gb": 64
      },
      {
        "name": "32-128",
        "cpu": 32,
        "memory_gb": 128
      },
      {
        "name": "48-192",
        "cpu": 48,
        "memory_gb": 192
      },
      {
        "name": "64-256",
        "cpu": 64,
        "memory_gb": 256
      },
      {
        "name": "96-384",
        "cpu": 96,
        "memory_gb": 384
      },
      {
        "name": "128-512",
        "cpu": 128,
        "memory_gb": 512
      }
    ],
    "gcp": [
      {
        "name": "4-16",
        "cpu": 4,
        "memory_gb": 16
      },
      {
        "name": "4-32",
        "cpu": 4,
        "memory_gb": 32
      },
      {
        "name": "8-32",
        "cpu": 8,
        "memory_gb": 32
      },
      {
        "name": "16-64",
        "cpu": 16,
        "memory_gb": 64
      },
      {
        "name": "32-128",
        "cpu": 32,
        "memory_gb": 128
      },
      {
        "name": "48-192",
        "cpu": 48,
        "memory_gb": 192
      },
      {
        "name": "64-256",
        "cpu": 64,
        "memory_gb": 256
      },
      {
        "name": "80-320",
        "cpu": 80,
        "memory_gb": 320
      },
      {
        "name": "96-384",
        "cpu": 96,
        "memory_gb": 384
      },
      {
        "name": "128-512",
        "cpu": 128,
        "memory_gb": 512
      }
    ]
  },
  "available_roles": ["writer", "reader", "copyjob"]
}

Response fields¶
Field	Type	Description
cloud_regions	Object	Available cloud regions grouped by provider.
available_sizes	Object	Available replica sizes grouped by provider.
available_sizes.<provider>[].name	String	Replica size in `cpu-memory` format.
available_sizes.<provider>[].cpu	Integer	Number of vCPUs for the replica size.
available_sizes.<provider>[].memory_gb	Integer	Amount of memory in GB for the replica size.
available_roles	Array[String]	Cluster roles that can be managed in scaling and rebalancing operations.

Request body requirements:

PUT /v0/organizations/{organization_id}/clusters/{cluster_id}/weights expects old_weights and new_weights.
POST /v0/organizations/{organization_id}/clusters/{cluster_id}/replicas expects replica_size, existing_replicas, and new_replica.
DELETE /v0/organizations/{organization_id}/clusters/{cluster_id}/replicas/{replica_name} expects old_weights and new_weights.