v1

OpenAPI 3.1.02026-07-13632897.9 KB
clarity

Get Clusters

Retrieve user's cluster snapshot.

Called by Clarity MCP server to fetch persisted data for cross-session continuity. Single-row model: each user has at most one snapshot (enforced by UNIQUE constraint).

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

Returns: 200: Cluster snapshot data 401: Missing or malformed X-User-ID header 403: Invalid internal secret (production only) 404: No cluster snapshot found for user

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.

get/api/clarity/clusters

Headers

X-Internal-Secretstring nullable
X-User-IDstring nullable

Response

Successful Response

cluster_idstring uuid required
cluster_dataobject required
created_atstring date-time required
content_hashstring nullable
thoughts_exhaustedboolean
correctly_clusteredboolean nullable