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.

PATCH /v1/clusters/{cluster_identifier}

Partially Update Cluster

cURL

curl --request PATCH \
  --url https://api.mixpeek.com/v1/clusters/{cluster_identifier} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "cluster_name": "<string>",
  "description": "<string>",
  "metadata": {},
  "llm_labeling": {
    "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"
  },
  "filters": {},
  "face_cluster_merge": {
    "enabled": true,
    "centroid_cosine_threshold": 0.55,
    "bbox_iou_threshold": 0.4,
    "scene_jaccard_threshold": 0.3,
    "bbox_field": "bbox",
    "frame_field": "frame_number",
    "scene_field": "scene_id"
  },
  "sample_size": 123,
  "algorithm_params": {},
  "source_cluster_ids": [
    "<string>"
  ]
}
'

200

{
  "cluster_name": "products_clip_hdbscan",
  "cluster_type": "vector",
  "collection_ids": [
    "col_products_v1",
    "col_products_v2"
  ],
  "llm_labeling": {
    "enabled": true,
    "labeling_inputs": {
      "input_mappings": [
        {
          "input_key": "text",
          "path": "description",
          "source_type": "payload"
        }
      ]
    },
    "model_name": "gpt-4o-mini-2024-07-18",
    "provider": "openai"
  },
  "vector_config": {
    "clustering_method": "hdbscan",
    "feature_uri": "mixpeek://clip_vit_l_14@v1/embedding",
    "hdbscan_parameters": {
      "min_cluster_size": 10,
      "min_samples": 5
    },
    "sample_size": 5000
  }
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

cluster_identifier · string · required

Cluster ID or name

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

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 · Metadata · object | null

Updated metadata for the cluster

llm_labeling · LLMLabeling · object | null

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.

Show child attributes

Example:

{
  "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"
}

filters · Filters · object | null

Updated pre-filter for clustering input documents. Overrides the cluster's stored filter on subsequent execute calls.

face_cluster_merge · FaceClusterMergeConfig · object | null

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.

Show child attributes

sample_size · integer | null

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. KMeans supports up to 1M; O(N²) algorithms are capped at 100K by the engine.

Required range: x <= 1000000

algorithm_params · Algorithm Params · object | null

Updated algorithm parameters (e.g. min_cluster_size, min_samples for HDBSCAN). Takes effect on the next POST /v1/clusters/{id}/execute.

source_cluster_ids · string[] | null

Updated source clusters of a composite cluster. Each must be a vector cluster in this namespace with this cluster's feature_uris, and a cluster cannot name itself. The cluster's input collections become the sources' input collections. Takes effect on the next POST /v1/clusters/{id}/execute.

Minimum array length: 1

layout_stability · enum<string> | null

Updated layout-stability mode: 'align' keeps the map stable across runs (default behavior), 'transform' reuses the previous run's saved projection when compatible, 'none' re-layouts every run. Takes effect on the next POST /v1/clusters/{id}/execute. Omit to leave the stored value untouched.

Available options: none, transform, align

Response

200

application/json

Successful Response

Cluster metadata stored in MongoDB.

collection_ids · string[] | null

Collections to cluster together

Minimum array length: 1

source_cluster_ids · string[] | null

Makes this a composite cluster: it groups the centroids of these clusters' runs instead of documents. Each id must be a vector cluster in this namespace with the same feature_uris as this one. Executing a composite cluster without a mode runs mode 'composite' over the newest completed run of each source cluster, one per partition (a partition is a run's filters). Vector clusters only.

Minimum array length: 1

cluster_name · string | null

Optional human-friendly name for the clustering job

description · string | null

Optional description of the cluster, stored with it

metadata · Metadata · object

Additional user-defined metadata for the cluster

cluster_type · enum<string> · default: vector

Vector or attribute clustering

Available options: vector, attribute

vector_config · VectorBasedConfig · object | null

Required when cluster_type is 'vector'

Show child attributes

Example:

{
  "algorithm_params": { "min_cluster_size": 10, "min_samples": 5 },
  "clustering_method": "hdbscan",
  "feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
  "sample_size": 1000
}

attribute_config · AttributeBasedConfig · object | null

Required when cluster_type is 'attribute'

Show child attributes

Example:

{
  "attributes": ["category"],
  "hierarchical_grouping": false
}

filters · LogicalOperator · object | null

Optional filters to pre-filter documents before clustering (same format as list documents). Applied during the vector store scroll before parquet export. Useful for clustering subsets like: status='active', category='electronics', etc.

Show child attributes

llm_labeling · LLMLabeling · object | null

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.

Show child attributes

Example:

{
  "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"
}

enrich_source_collection · boolean · default: false

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.

source_enrichment_config · SourceEnrichmentConfig · object | null

Configuration for source collection enrichment (only used if enrich_source_collection=True). Controls which fields are added to source documents and field naming conventions.

Show child attributes

Example:

{
  "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"
    }
  ]
}

auto_execute_on_batch · boolean · default: false

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.

auto_execute_min_documents · integer | null

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.

auto_execute_cooldown_seconds · integer · default: 3600

Minimum time (in seconds) between automatic cluster executions. Only used when auto_execute_on_batch=True. Default: 3600 (1 hour).

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 · ClusterStats · object | null

Clustering quality metrics

Show child attributes

status · enum<string> · default: PENDING

Clustering job status

Available options: PENDING, QUEUED, IN_PROGRESS, PROCESSING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELED, INTERRUPTED, UNKNOWN, SKIPPED, DRAFT, ACTIVE, ARCHIVED, SUSPENDED, DEACTIVATED

task_id · string | null

Associated task ID for clustering job

last_run_id · string | null

Run ID of the most recent successful clustering execution. Used to retrieve execution results.

created_at · string<date-time>

When the cluster was created

updated_at · string<date-time>

When the cluster was last updated