Diagnose — API reference

Failure clustering, the failure-mode taxonomy and Issues, topics, and insights.

clusters

GET /clusters

List Clusters

POST /clusters/assign

Assign Sessions

Classify sessions against the project’s existing failure clusters without re-clustering. Each result is assigned / novel / unassigned / no_model / unavailable / not_found; a novel session raises a new-failure-mode insight.

GET /clusters/configs

List Configs

List the project’s clustering configs. lifecycle filters by stage (finalized default | experimental | all) — but the ACTIVE config is ALWAYS included (never hide what runs). Sort: active first, then updated_at desc.

POST /clusters/configs

Create Config

Create a new config (stamped experimental, is_active=0, knobs defaulting from CLUSTER_SETTINGS_DEFAULTS and clamped like the settings patch). 422 when name is blank.

POST /clusters/configs/estimate

Estimate Config

Cheap eligible-failure-set count for an UNSAVED knob set — powers the fine-tune preview (a count only, no ML dry-run). Degrades to {eligible: 0,...} on any error.

GET /clusters/configs/{config_id}

Get Config

A single config. 404 when it belongs to another project.

PATCH /clusters/configs/{config_id}

Patch Config

Edit a config’s name/description/knobs (same clamps + nullable-meaningful scoreMetricKey as the settings patch). 404 out-of-scope; 422 on a blanked name.

DELETE /clusters/configs/{config_id}

Delete Config

Delete a config. Refused (409) when it is the ACTIVE one (activate another first) or the project’s ONLY config. 404 out-of-scope.

POST /clusters/configs/{config_id}/activate

Activate Config

Make this config the project’s active one — atomically deactivating every other config in the project (enforces the exactly-one-active invariant). 404 out-of-scope.

PATCH /clusters/configs/{config_id}/lifecycle

Patch Config Lifecycle

Move a config through its curation lifecycle: experimental → finalized → archived. A LABEL ONLY — never changes what runs, only the default list visibility. 404 out-of-scope; 422 on an unknown stage.

GET /clusters/failure-modes

Failure Modes Hero

The Failure Modes hero page (plan B1) in one call: readiness (zero-state), the ranked active failure-mode clusters enriched with root-cause hypothesis / typed-remediation chip / daily-volume trend / NEW flag, plus honest freshness (“Last analyzed”) and sample-based estimate reporting. Project-scoped. Purely additive — no storage change (the Cluster model already carries root_cause/remediation/first_seen_at/status).

GET /clusters/readiness

Readiness

Backs the Failure Modes zero-state (plan B1): the windowed failure-set count vs the first-run threshold, plus whether the first run has landed. Project-scoped.

POST /clusters/run

Run Clustering

Manually trigger a clustering run. Project-scoped.

GET /clusters/scatter

Scatter Points

Cluster-member scatter. Each point carries its cluster’s L1 bucket key and the response carries a finite buckets legend [{key, label, count}] (count = points, sorted desc) so the UI can colour by ~10 buckets instead of an unbounded label set.

GET /clusters/settings

Get Settings Endpoint

PATCH /clusters/settings

Patch Settings Endpoint

GET /clusters/{cluster_id}

Get Cluster

PATCH /clusters/{cluster_id}

Rename Cluster Endpoint

Rename a cluster and PIN the name: a pinned label survives future clustering relabels. Requires write access, object-level scope 404, 422 on a blank label. Declared after /settings + /configs so PATCH /{cluster_id} never shadows them.

GET /clusters/{cluster_id}/exemplars

Cluster Exemplars

Representative sessions of a cluster, most typical first, capped at limit. A cluster in another project returns 404.

POST /clusters/{cluster_id}/merge

Merge Clusters Endpoint

Manually merge one or more source clusters INTO cluster_id. Mirrors the taxonomy failure-mode merge: MANAGE_TAXONOMY-gated, object-level scope (target + each source must be in the caller’s project — else 404), a cross-project guard (a source in a different project 404s), and 422 on an empty source set or a self-merge. Members are reassigned + deduped by storage.merge_clusters; sources are soft-resolved. Returns the merged target cluster.

taxonomy

GET /taxonomy/failure-modes

List Failure Modes

POST /taxonomy/failure-modes

Create Failure Mode

POST /taxonomy/failure-modes/import

Import Failure Modes Endpoint

Bulk-import a starter taxonomy (Phase C1).

POST /taxonomy/failure-modes/import-file

Import Failure Modes File

Bulk-import a taxonomy from an uploaded file (CSV or JSON) — the enterprise “upload our failure taxonomy” path.

GET /taxonomy/failure-modes/import-template

Failure Modes Import Template

Download the CSV import template (header + two illustrative rows).

GET /taxonomy/failure-modes/{mode_id}

Get Failure Mode

PATCH /taxonomy/failure-modes/{mode_id}

Patch Failure Mode

DELETE /taxonomy/failure-modes/{mode_id}

Delete Failure Mode

Hard-delete a failure mode and its cluster-evidence links (project-scoped, audited).

POST /taxonomy/failure-modes/{mode_id}/links

Add Link

DELETE /taxonomy/failure-modes/{mode_id}/links/{cluster_id}

Delete Link

POST /taxonomy/failure-modes/{mode_id}/merge

Merge Failure Mode

POST /taxonomy/failure-modes/{mode_id}/split

Split Failure Mode

GET /taxonomy/issues

List Issues

GET /taxonomy/issues/{mode_id}

Get Issue

PATCH /taxonomy/issues/{mode_id}/lifecycle

Patch Issue Lifecycle

failure-modes

GET /failure-modes

Get Failure Modes

topics

POST /topics

Create Topic

GET /topics/atlas

Get Atlas

POST /topics/spaces

Create Space

GET /topics/{topic_id}

Get Topic

PATCH /topics/{topic_id}

Patch Topic

POST /topics/{topic_id}/datasets

Create Dataset

GET /topics/{topic_id}/examples

Get Examples

POST /topics/{topic_id}/merge

Merge Topic

POST /topics/{topic_id}/split

Split Topic

insights

GET /insights/diagnose

Diagnose

The Diagnose feed: {issues:[{projectId, type:'cluster'|'regression', label, affected, confidence, link, asOf}]} — failure clusters and score regressions across the accessible projects, filterable by range / from / to and repeatable project_id.

GET /insights/fix

Fix

The Fix feed: {remediations:[{projectId, clusterLabel, summary, likelyCause, recommendation, confidence, affected}]} — suggested remediations for the latest failure clusters, highest-impact first. Repeatable project_id narrows the scope.

GET /insights/observe

Observe

{fleet:{sessions, errorRate, p99Ms, spendUsd}, anomalies:[…]}.

POST /insights/refresh

Refresh

Run the anomaly + regression detectors now, within the caller’s pinned tenant schema, over their accessible project set (None ⇒ all projects in the schema). Persists to the insight store + dispatches newly-surfaced insights to the configured sinks. Returns {detected, surfaced} counts. This is the synchronous counterpart to the nightly scheduler job — useful for the demo and for a ‘refresh now’ UI affordance.

GET /insights/summary

Summary

{headline, body, llm, model, stats, empty, cached, generatedAt, briefing} — a short briefing over the current fleet KPIs + top anomalies / issues / remediations for the scope + window.

POST /insights/summary/briefing

Request Briefing

Request generation of the LLM narrative for a scope + window. Idempotent.

GET /insights/summary/briefing/{briefing_id}

Get Briefing

The cheap poll: ONE indexed row read, no measure or cluster queries — this is polled every few seconds while a narrative generates.

GET /insights/{insight_id}/feedback

Get Feedback

List the feedback recorded for an insight (most recent first). A scoped member/viewer may only read feedback for an insight in a project they can access; an unknown id (incl. one outside the pinned tenant schema) returns an empty list — no existence leak.

POST /insights/{insight_id}/feedback

Submit Feedback

Record user feedback on a surfaced insight. verdict ∈ useful|actioned|not_useful|wrong|dismissed — a negative verdict (not_useful/ wrong/dismissed) mutes the insight on the next detection pass until its signal resolves and recurs. 404 if the insight id is unknown.