# Cluster Management API

This section talks about how to use the Typesense Cloud Cluster Management API.

If you're looking for the Typesense Server API docs, see here.

# Workflow

Here's a typical sequence of API Calls you'd perform when using this API:

  1. Create a new cluster (which is an asynchronous process that will take 4 - 5 minutes).
  2. Poll the single cluster info endpoint to get the status of the cluster.
  3. Once the cluster has status: in_service, save the hostnames field returned by the cluster info endpoint.
  4. Generate Typesense API keys for the cluster and store these keys in a secrets store on your side.
  5. Now, you can make Typesense API calls directly to your new cluster using the hostnames in Step 3 and API Keys in Step 4.
  6. Once you're done with the cluster, you can terminate it using the lifecycle endpoint.

The rest of this document will talk about the individual endpoints.

# Create new cluster

This endpoint lets you provision a new cluster under your Typesense Cloud account.

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "memory": "0.5_gb",
          "vcpu": "2_vcpus_1_hr_burst_per_day",
          "regions": ["oregon"],
        }'

Response:

{
  "success": true,
  "cluster": {
    "id": "az9p28gwxfdsye40d",
    "name": null,
    "memory": "0.5_gb",
    "vcpu": "2_vcpus_1_hr_burst_per_day",
    "gpu": "no",
    "high_performance_disk": "no",
    "typesense_server_version": "0.23.1",
    "high_availability": "no",
    "search_delivery_network": "off",
    "load_balancing": "no",
    "regions": [
      "oregon"
    ],
    "auto_upgrade_capacity": null,
    "usage": {
      "runtime_hours": 0,
      "used_bandwidth_kb": {
        "last_7_days": {}
      }
    },
    "provisioned_by": {
      "user_name": "API Key: YOUR-API-KEY*****",
      "user_type": "API Key"
    },
    "provisioned_at": 1663382519,
    "status": "provisioning"
  }
}

# Parameters

You can use any of the following parameters inside the payload of the above API call:

# memory

How much RAM this cluster should have. Required

You can use any of the following values:

memory
0.5_gb
1_gb
2_gb
4_gb
8_gb
16_gb
32_gb
64_gb
96_gb
128_gb
192_gb
256_gb
384_gb
512_gb
768_gb
1024_gb

# vcpu

How many CPU cores this cluster should have. Required

Only certain CPU configuration are available with particular RAM configurations. The table below lists all available configurations:

memory vcpu
0.5_gb 2_vcpus_1_hr_burst_per_day
1_gb 2_vcpus_2_hr_burst_per_day
2_gb 2_vcpus_4_hr_burst_per_day
4_gb 2_vcpus_4_hr_burst_per_day
2_vcpus
8_gb 2_vcpus_7_hr_burst_per_day
2_vcpus
4_vcpus
16_gb 2_vcpus
4_vcpus_5_hr_burst_per_day
4_vcpus
8_vcpus
32_gb 4_vcpus
8_vcpus_4_hr_burst_per_day
8_vcpus
16_vcpus
64_gb 8_vcpus
16_vcpus
32_vcpus
96_gb 12_vcpus
24_vcpus
48_vcpus
128_gb 4_vcpus
16_vcpus
32_vcpus
64_vcpus
192_gb 24_vcpus
48_vcpus
96_vcpus
256_gb 8_vcpus
32_vcpus
64_vcpus
128_vcpus
384_gb 48_vcpus
96_vcpus
128_vcpus
512_gb 16_vcpus
64_vcpus
128_vcpus
768_gb 24_vcpus
96_vcpus
192_vcpus
1024_gb 32_vcpus
64_vcpus
128_vcpus

# regions

An array with one or more regions where the nodes should be geographically placed. Required

  • For a non-Search-Delivery-Network cluster, the array should have only one region.
  • For a Search Delivery Network (SDN) cluster, the array should have 3 or 5 regions depending on the number of SDN regions.

The table below lists all available regions:

regions
n_california
oregon
n_virginia
ohio
canada
sao_paulo
ireland
london
paris
zurich
frankfurt
stockholm
milan
spain
cape_town
bahrain
uae
mumbai
hyderabad
singapore
jakarta
seoul
osaka
tokyo
melbourne
sydney

# gpu

When set to yes, it enables the use of a GPU to accelerate embedding generation when using built-in ML models both during indexing and searching.

This option is only available with the following RAM / CPU configurations:

ram vcpu
8_gb 4_vcpus
16_gb 4_vcpus
16_gb 8_vcpus
32_gb 8_vcpus
32_gb 16_vcpus
64_gb 16_vcpus
64_gb 32_vcpus
128_gb 32_vcpus
128_gb 64_vcpus
192_gb 48_vcpus
256_gb 64_vcpus
384_gb 96_vcpus

Default: no

# high_availability

When set to yes, at least 3 nodes are provisioned in 3 different data centers to form a highly available (HA) cluster and your data is automatically replicated between all nodes.

Default: no

# search_delivery_network

When not off, nodes are provisioned in different regions and the node that's closest to it's originating location serves the traffic.

Default: off

The table below lists all available options:

search_delivery_network
off
3_regions
5_regions

IMPORTANT: Make sure you set high_availability to yes when you turn on Search Delivery Network.

# high_performance_disk

When set to yes, the provisioned hard disk will be co-located on the same physical server that runs the node.

Default: no

IMPORTANT: This option is only available when:

  • The cluster has High Availability turned on
  • The cluster does not have a burst CPU type.

# typesense_server_version

The Typesense Server version to use for this cluster.

Default: Latest GA release version.

# name

A string to identify the cluster for your reference in the Typesense Cloud Web console.

Default: null

# auto_upgrade_capacity

When set to true, your cluster will be automatically upgraded when best-practice RAM/CPU thresholds are exceeded in a 12-hour rolling window.

Default: false

# Response Parameters

Most response parameters are similar to the request parameters above.

We've documented response-specific parameters below:

# status

The state of the cluster.

It can have the following values:

status Description
provisioning The cluster's nodes are being provisioned
initializing Typesense cluster is being setup
in_service Cluster is ready for use
deprovisioning Cluster is being deprovisioned
suspended Cluster was suspended due to billing issues
terminated Cluster was terminated

# Generate API key

This endpoint can be used to generate Typesense Server API Keys for your cluster.

You can only generate API keys for a cluster, once its status changes to in_service. New clusters take at least 4 minutes to go from provisioning status to in_service.

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/api-keys" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

{
  "success": true,
  "api_keys": {
    "admin_key": "cBKqFPEcGRAS7RIKi3h3FuJbj4Q9Rprk",
    "search_only_key": "y7CFw2zEgu09FFhoDgLzC99j0RwKi0kL"
  }
}

This API endpoint is the equivalent of clicking on the "Generate API Keys" button in the Cluster Dashboard on Typesense Cloud Web console.

# Get single cluster

This endpoint can be used to get information about a single cluster.

curl -X GET --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

{
  "id": "nuj9s7k6vplrg15yp",
  "name": null,
  "memory": "0.5_gb",
  "vcpu": "2_vcpus_1_hr_burst_per_day",
  "gpu": "no",
  "high_performance_disk": "no",
  "typesense_server_version": "0.23.1",
  "high_availability": "yes",
  "search_delivery_network": "off",
  "load_balancing": "yes",
  "regions": [
    "mumbai",
    "mumbai",
    "mumbai"
  ],
  "auto_upgrade_capacity": null,
  "hostnames": {
    "load_balanced": "nuj9s7k6vplrg15yp.a1.typesense.net",
    "nodes": [
      "nuj9s7k6vplrg15yp-1.a1.typesense.net",
      "nuj9s7k6vplrg15yp-2.a1.typesense.net",
      "nuj9s7k6vplrg15yp-3.a1.typesense.net"
    ]
  },
  "usage": {
    "runtime_hours": 1,
    "used_bandwidth_kb": {
      "last_7_days": {}
    }
  },
  "provisioned_by": {
    "user_name": "API Key: sc4DyvAzf*****",
    "user_type": "API Key"
  },
  "provisioned_at": 1663616196,
  "status": "in_service"
}

# List all clusters

This endpoint can be used to list all clusters under this account.

curl -X GET --location "https://cloud.typesense.org/api/v1/clusters" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY"

Response:

{
  "page": 1,
  "per_page": 1,
  "total": 2,
  "clusters": [
    {
      "id": "az9p28gwxfdsye40d",
      "name": null,
      "memory": "0.5_gb",
      "vcpu": "2_vcpus_1_hr_burst_per_day",
      "gpu": "no",
      "high_performance_disk": "no",
      "typesense_server_version": "0.23.1",
      "high_availability": "no",
      "search_delivery_network": "off",
      "load_balancing": "no",
      "regions": [
        "oregon"
      ],
      "auto_upgrade_capacity": false,
      "usage": {
        "runtime_hours": 5643,
        "used_bandwidth_kb": {
          "last_7_days": {}
        }
      },
      "provisioned_by": {
        "user_name": "John Doe",
        "user_type": "User"
      },
      "provisioned_at": 1663382520,
      "status": "initializing"
    }
  ]
}

# Parameters

You can use the following query parameters with this endpoint:

# per_page

The number of results per page.

Default: 10

# page

Page number to fetch

Default: 1

# Update cluster attributes

This endpoint can be used to update select cluster attributes:

  • auto_upgrade_capacity
  • name
curl -X PATCH --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "auto_upgrade_capacity": true,
          "name": "New Name"
        }'

Response:

{
  "success": true,
  "cluster": {
    "id": "az9p28gwxfdsye40d",
    "name": "New Name",
    "memory": "0.5_gb",
    "vcpu": "2_vcpus_1_hr_burst_per_day",
    "gpu": "no",
    "high_performance_disk": "no",
    "typesense_server_version": "0.23.1",
    "high_availability": "no",
    "search_delivery_network": "off",
    "load_balancing": "no",
    "regions": ["oregon"],
    "auto_upgrade_capacity": true,
    "usage": {
      "runtime_hours": 5643,
      "used_bandwidth_kb": {
        "last_7_days": {}
      }
    },
    "provisioned_by": {
      "user_name": "John Doe",
      "user_type": "User"
    },
    "provisioned_at": 1663382520,
    "status": "in_service"
  }
}

# Terminate cluster

This endpoint terminates a running cluster.

This action cannot be undone. Once a cluster is terminated, all data in it is destroyed permanently as a security and privacy measure.

curl -X POST --location "https://cloud.typesense.org/api/v1/clusters/<ClusterID>/lifecycle" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-TYPESENSE-CLOUD-MANAGEMENT-API-KEY: YOUR-API-KEY" \
    -d '{
          "lifecycle_action": "terminate"
        }'

Response:

{
  "success": true,
  "message": "Cluster termination has been initiated"
}

# Parameters

This endpoint takes a single parameter lifecycle_action and should have the value terminate

Last Updated: 10/27/2023, 12:35:06 PM