Skip to main content
PATCH
/
v1
/
clusters
/
{cluster_identifier}
Partially Update Cluster
curl --request PATCH \
  --url https://api.mixpeek.com/v1/clusters/{cluster_identifier} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <x-namespace>' \
  --data '{
  "cluster_name": "<string>",
  "description": "<string>",
  "metadata": {}
}'
{
  "cluster_name": "products_clip_hdbscan",
  "cluster_type": "vector",
  "collection_ids": [
    "col_products_v1",
    "col_products_v2"
  ],
  "llm_labeling": {
    "enabled": true,
    "model_name": "gpt-4"
  },
  "vector_config": {
    "clustering_method": "hdbscan",
    "feature_extractor_name": "clip_vit_l_14",
    "hdbscan_parameters": {
      "min_cluster_size": 10,
      "min_samples": 5
    },
    "sample_size": 5000
  }
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

​
X-Namespace
string
required

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Examples:

"ns_abc123def456"

"production"

"my-namespace"

Path Parameters

​
cluster_identifier
string
required

Cluster ID or name

Body

application/json

Request model for partially updating a cluster (PATCH operation).

​
cluster_name
string | null

Updated name for the cluster

​
description
string | null

Updated description for the cluster

​
metadata
object | null

Updated metadata for the cluster

Response

Successful Response

Cluster metadata stored in MongoDB.

​
collection_ids
string[]
required

Collections to cluster together

Minimum length: 1
​
cluster_name
string | null

Optional human-friendly name for the clustering job

​
cluster_type
enum<string>

Vector or attribute clustering

Available options:
vector,
attribute
​
vector_config
object | null

Required when cluster_type is 'vector' Configuration for vector-based clustering.

​
attribute_config
object | null

Required when cluster_type is 'attribute' Configuration for attribute-based clustering.

Attribute-based clustering groups documents by metadata attributes (e.g., category, brand, status) instead of vector similarity. This is useful for organizing content by business logic rather than semantic similarity.

Examples: - Group products by category and brand - Organize orders by status and priority - Cluster content by author and topic

Examples:
{
  "attributes": ["category"],
  "description": "Simple category clustering",
  "hierarchical_grouping": false
}
{
  "attributes": ["category", "brand"],
  "description": "Hierarchical category → brand clustering",
  "hierarchical_grouping": true
}
{
  "aggregation_method": "most_frequent",
  "attributes": ["status", "priority"],
  "description": "Order status and priority (flat)",
  "hierarchical_grouping": false
}
​
llm_labeling
object

Configuration for LLM-based cluster labeling

​
cluster_id
string

Unique cluster identifier

​
parquet_path
string | null

S3 path to parquet files with cluster data

​
members_key
string | null

S3 key to members.parquet (if saved)

​
num_clusters
integer | null

Number of clusters found

​
cluster_stats
object | null

Clustering quality metrics Basic clustering quality metrics.

​
status
enum<string>

Clustering job status

Available options:
PENDING,
IN_PROGRESS,
PROCESSING,
COMPLETED,
FAILED,
CANCELED,
UNKNOWN,
SKIPPED,
DRAFT,
ACTIVE,
ARCHIVED,
SUSPENDED
​
task_id
string | null

Associated task ID for clustering job

​
created_at
string<date-time>

When the cluster was created

​
updated_at
string<date-time>

When the cluster was last updated

​
metadata
object

Additional user-defined metadata for the cluster