Partially Update Cluster
This endpoint partially updates a cluster (PATCH operation). Only provided fields will be updated. At minimum, metadata can always be updated. Immutable fields like cluster_id, status, and computed fields cannot be modified.
Documentation Index
Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Headers
REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
"Bearer YOUR_API_KEY"
"Bearer YOUR_STRIPE_API_KEY"
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'. Falls back to ?namespace= query parameter if the header is omitted.
"ns_abc123def456"
"production"
"my-namespace"
Path Parameters
Cluster ID or name
Body
Request model for partially updating a cluster (PATCH operation).
Updated name for the cluster
Updated description for the cluster
Updated metadata for the cluster
Updated LLM labeling configuration. Takes effect on the next POST /v1/clusters/{id}/execute — use this to correct a null labeling_inputs mapping that produced schema-metadata labels, without re-embedding or re-running HDBSCAN.
{
"description": "Text-only labeling with multiple fields",
"enabled": true,
"include_keywords": true,
"include_summary": true,
"labeling_inputs": {
"input_mappings": [
{
"input_key": "title",
"path": "title",
"source_type": "payload"
},
{
"input_key": "description",
"path": "description",
"source_type": "payload"
},
{
"input_key": "text",
"path": "text",
"source_type": "payload"
}
]
},
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
}Updated pre-filter for clustering input documents. Overrides the cluster's stored filter on subsequent execute calls.
Updated post-HDBSCAN face-identity merge configuration. Takes effect on the next POST /v1/clusters/{id}/execute. Pass an object with enabled=false to turn the merge pass off without removing the config; pass null in the patch to leave the stored value untouched.
Updated per-execution document cap. Takes effect on the next POST /v1/clusters/{id}/execute. Omit to leave the stored value untouched; set to an integer to change it. Hard max is 100,000 to keep O(N²) algorithms within RAM bounds.
x <= 100000Updated algorithm parameters (e.g. min_cluster_size, min_samples for HDBSCAN). Takes effect on the next POST /v1/clusters/{id}/execute.
Response
Successful Response
Cluster metadata stored in MongoDB.
Collections to cluster together
1Optional human-friendly name for the clustering job
Vector or attribute clustering
vector, attribute Required when cluster_type is 'vector'
{
"algorithm_params": { "min_cluster_size": 10, "min_samples": 5 },
"clustering_method": "hdbscan",
"description": "HDBSCAN clustering with multimodal embeddings",
"feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
"sample_size": 1000
}Required when cluster_type is 'attribute'
{
"attributes": ["category"],
"description": "Simple category clustering",
"hierarchical_grouping": false
}Optional filters to pre-filter documents before clustering (same format as list documents). Applied during Qdrant scroll before parquet export. Useful for clustering subsets like: status='active', category='electronics', etc.
Optional configuration for LLM-based cluster labeling. When provided with enabled=True, clusters will have semantic labels generated by LLM instead of generic labels like 'Cluster 0'. When not provided or enabled=False, uses fallback labels.
{
"description": "Text-only labeling with multiple fields",
"enabled": true,
"include_keywords": true,
"include_summary": true,
"labeling_inputs": {
"input_mappings": [
{
"input_key": "title",
"path": "title",
"source_type": "payload"
},
{
"input_key": "description",
"path": "description",
"source_type": "payload"
},
{
"input_key": "text",
"path": "text",
"source_type": "payload"
}
]
},
"model_name": "gpt-4o-mini-2024-07-18",
"provider": "openai"
}If True, cluster results are written back to source collection(s) in-place instead of creating new output collections. Documents will be enriched with cluster_id, cluster_label, distance_to_centroid, and optionally other metadata. Similar to taxonomy enrichment pattern.
Configuration for source collection enrichment (only used if enrich_source_collection=True). Controls which fields are added to source documents and field naming conventions.
{
"field_mappings": [
{
"source_field": "cluster_id",
"target_field": "category_id"
},
{
"source_field": "cluster_label",
"target_field": "category_name"
},
{
"source_field": "distance_to_centroid",
"target_field": "category_confidence"
}
]
}Automatically execute this cluster whenever a batch completes on any of its input collections. When True, a ClusterApplicationConfig entry is added to each input collection's cluster_applications field at creation time. The cluster will then auto-trigger after each batch completion (subject to cooldown and document threshold). When False (default), the cluster must be executed manually via the API.
Minimum number of documents required before auto-executing cluster. Only used when auto_execute_on_batch=True. If the collection has fewer documents than this threshold, clustering is skipped.
Minimum time (in seconds) between automatic cluster executions. Only used when auto_execute_on_batch=True. Default: 3600 (1 hour).
Unique cluster identifier
S3 path to parquet files with cluster data
S3 key to members.parquet (if saved)
Number of clusters found
Clustering quality metrics
Clustering job status
PENDING, QUEUED, IN_PROGRESS, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, UNKNOWN, SKIPPED, DRAFT, ACTIVE, ARCHIVED, SUSPENDED Associated task ID for clustering job
Run ID of the most recent successful clustering execution. Used to retrieve execution results.
When the cluster was created
When the cluster was last updated
Additional user-defined metadata for the cluster