---
title: "Create Cluster"
method: POST
path: "/api/clarity/clusters"
tags: ["clarity"]
---

# Create Cluster

`POST /api/clarity/clusters`

Upsert the user's cluster snapshot.

Called by Clarity MCP server after successful clustering.
Single-row model: INSERT if no snapshot exists, UPDATE if one does.

Headers:
    X-User-ID: User UUID (required)
    X-Internal-Secret: Internal API secret (required in production)

Body:
    cluster_data: {"clusters": [...]}
    thoughts_exhausted: bool
    correctly_clustered: bool | null

Returns:
    201: {"cluster_id": "...", "created_at": "..."}
    400: Invalid cluster_data structure
    401: Missing or malformed X-User-ID header
    404: User not found

Security:
    Validates X-Internal-Secret header to ensure request comes from
    trusted MCP server. In dev mode (INTERNAL_API_SECRET empty), this
    check is skipped.

## Headers

- `X-Internal-Secret` string, nullable
- `X-User-ID` string, nullable

## Request body

- CreateClusterRequest — Request body for POST /api/clarity/clusters.
  - `cluster_data` object, required
  - `content_hash` string, nullable
  - `thoughts_exhausted` boolean, nullable
  - `correctly_clustered` boolean, nullable

## Response `201`

Successful Response

- CreateClusterResponse — Response body for POST /api/clarity/clusters.
  - `cluster_id` string, uuid, required
  - `created_at` string, date-time, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/priority-guard/apis/priority-guardian.md) · [All operations](https://skmtc.net/priority-guard/apis/priority-guardian/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/priority-guard/priority-guardian/revisions/8579218b716d/schema)