> ## Documentation Index
> Fetch the complete documentation index at: https://docs.causeloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Concepts
> The entities and loop that make Causeloop work — organization, workspace, membership, issue, pattern, cluster, prediction, recommendation, connector, plan, and seat.
Understanding these building blocks will help you navigate every other part of the documentation.
## The core loop
Causeloop is organized around a single closed loop that turns raw failures into verified fixes. Under the hood, "predicts" and "verified" are not figures of speech — they're a fitted point-process model and a statistical monitor, respectively, and every number either endpoint returns says exactly which run produced it.
A discrete failure event — an incident, a defect, a failed check. Issues arrive automatically from connected sources or are created directly via the API or UI, and are recorded first as an [event](#event-log--projections) in the append-only log.
An [engine run](#event-log--projections) groups related issues by shared root-cause fingerprint (Leiden partition + deterministic cross-check). A pattern surfaces the recurring failure behind a set of issues rather than treating each one as isolated. Analysts can [pin](#pins) constraints the clustering must honor on every future run.
From each pattern's fitted [hazard model](#hazard-model), Causeloop forecasts where and when the failure is likely to recur — giving you a window to act before it does. If there isn't yet enough history to fit, the API says so explicitly rather than guessing.
Causeloop proposes a concrete remediation with a computed business case, then runs [verification](#verification-loop) — a statistical monitor, not a status flag — to prove the pattern's intensity actually dropped before marking it `implemented`.
The loop closes when verification confirms the fix held. If new issues matching the pattern appear after a fix, the loop reopens automatically.
***
## Event log & projections
Every mutation in Causeloop starts as an event, not a row update. Ingesting an issue writes an `issue.ingested` event; editing a field appends `field_updated` / `attr_corrected`; pinning, activating a config version, and a fix verifying all append their own event types. The `issues`, `patterns`, and other rows you read back over the REST API are **projections** — rebuilt deterministically from this append-only log, never the source of truth themselves.
| Field | Notes |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `content_hash` | Hash of the event payload — the basis for proving a replay is byte-identical. |
| `occurred_at` | When the underlying failure actually happened (drives the hazard model's point process) — distinct from when it was logged. |
| `actor` | Who or what produced the event (user, service account, or the engine itself). |
Two read surfaces expose the log directly: `GET /workspaces/current/events` (workspace-wide, cursor-paginated, filterable by type) and `GET /issues/{id}/events` (one issue's ordered history). `GET /activity` remains the human-friendly narrative view of the same underlying events.
## Provenance
Every computed number — a hazard forecast, a prediction's `p_recurrence`, a recommendation's ROI, a report's figures — carries a `provenance` object:
```json theme={null}
{
"run_id": "run_01j...",
"manifest_hash": "sha256:9c2e...",
"config_versions": { "hazard": "hz#a91f...", "cluster": "cl#7b02..." }
}
```
This is not optional metadata; it's how you trace any number back to exactly which engine run, which snapshot of the event log, and which config version hashes produced it. Two numbers with different provenance are never assumed comparable.
## Abstention & the review queue
Classification is allowed to answer "I don't know." Extraction and root-cause return a **prediction set** — a conformal set of candidate values with a guaranteed `coverage_level`, not a single point guess. A singleton set writes the value straight through (`origin: "extracted"`); a multi-value or empty set writes `null` and creates a `/review-queue` item instead of a low-confidence guess.
A human resolution (`POST /review-queue/{id}/resolve`) appends an event, always wins over the model (`origin: "human"`), and joins the calibration set that keeps future coverage honest — `GET /ai/calibration/{task}` tracks empirical coverage against target, and coverage that drifts more than 3 points below target automatically flips the task into abstain-more mode.
## Hazard model
Recurrence risk — predictions, time-to-repeat (`T̂_R`), crest alerts — is not an LLM guess. It's a fitted point-process model per pattern (`powerlaw_nhpp_hawkes_v1`): baseline intensity, a power-law aging term, Hawkes self-excitation, covariate priors (verification pending / churn intensity / severity history), and shrinkage for low-count patterns. `GET /patterns/{id}/hazard` is the canonical resource — forecast per horizon, the time-to-repeat interval, and a `crest_alert` when accelerating intensity crosses a threshold for consecutive runs. When there isn't enough history to fit, the endpoint returns `404 not_fitted` with a `reason` (`insufficient_events` or `no_timestamps`) instead of a placeholder curve.
## Pins
Analysts sometimes know something the graph doesn't yet — two patterns are really one, or an issue was mis-clustered. Pins (`POST /patterns/{id}/pins`, actions `merge_into` / `exclude_issue` / `include_issue` / `split`) are events, and the clustering anchorer honors them as **hard constraints** on every subsequent run — a pin beats the majority vote. This is the single, auditable replacement for the old link/unlink/merge affordances, which silently fought the engine on the next recompute.
## Verification loop
A recommendation isn't "done" when someone marks it implemented — it's done when the theme's failure intensity measurably drops. `POST /recommendations/{id}/attest` starts monitoring; `GET /recommendations/{id}/verification` returns a CUSUM (cumulative-sum) statistic tracked against a decision boundary derived from the fix's own counterfactual target, plus an expected decision window. When the statistic crosses the boundary, a `fix.verified` (or `fix.failed`) event fires, updates the theme's severity input for the next hazard fit, and stamps the recommendation — this endpoint is the product's proof-of-value artifact, not a checkbox.
## Config registry
Everything that used to be a hardcoded constant or a single mutable document is now a versioned, hash-identified config under `/configs/{kind}` — `rubric` (criticality scoring), `cluster` (edge weights, Leiden parameters), `hazard` (covariate priors, crest thresholds), `rate-card` (financial modeling inputs), and `taxonomy` (theme/bone vocabulary). Versions are immutable and content-hashed at creation; activation is a separate, privileged, audited step (`POST /configs/{kind}/versions/{v}/activate`). Run manifests pin config **hashes**, not labels, so a run's inputs are exactly reproducible — and activating a new `cluster` or `hazard` version invalidates downstream partitions by design, so the next run must be `mode: full`.
***
## Tenancy model
The top-level account — one per client. Carries the plan, seat count, and billing identity. Status: `active`, `suspended`, or `cancelled`.
The data boundary owned by an organization. All issues, patterns, connectors, and settings live inside a workspace. One organization typically has one workspace, but the model supports more.
The link between a user and a workspace. Carries the role that governs what the user can do inside that workspace.
### Organization
An organization is the client entity. It owns one or more workspaces and controls plan-level constraints:
| Field | Notes |
| ------------- | -------------------------------------------- |
| `slug` | URL-safe unique identifier (e.g. `acme`) |
| `plan` | `free` / `starter` / `growth` / `enterprise` |
| `seats_total` | Maximum active memberships |
| `status` | `active` / `suspended` / `cancelled` |
### Workspace
A workspace is the operational data boundary. Every API call resolves to a single workspace; Row-Level Security (RLS) enforces that no query can read another tenant's data.
| Field | Notes |
| -------------- | ------------------------------------------------------ |
| `slug` | Unique within the organization |
| `timezone` | Default display timezone for all reports |
| `sso_enforced` | When true, password login is blocked for the workspace |
Each workspace has a companion `workspace_settings` record controlling AI confidence thresholds, retention policies, and alert sensitivity, and an `onboarding_state` record that drives the setup wizard.
### User
A user is a global identity (unique by email). The `external_id` field stores the upstream identity provider's subject ID (WorkOS, or another configured OIDC provider) when the user authenticates through `POST /auth/exchange`.
### Membership
A membership joins a user to a workspace with a role. Roles are cumulative — each role includes all permissions of the roles below it:
| Role | Can do |
| --------- | ----------------------------------------------------------------------------------------------- |
| `viewer` | Read issues, patterns, predictions, recommendations, and reports |
| `analyst` | Everything above, plus create/update issues, link patterns, trigger analysis, create connectors |
| `admin` | Everything above, plus invite members, manage settings, create alert rules, export data |
| `owner` | Everything above, plus manage organization settings, billing, and SSO |
A user can belong to multiple workspaces with different roles in each.
***
## Product entities
### Issue
An issue is a single failure event ingested from a connected source or created manually.
| Field | Values |
| ------------ | --------------------------------------------------------------------------------- |
| `severity` | `p1` (critical) · `p2` · `p3` · `p4` |
| `status` | `open` · `in_loop` · `mitigating` · `resolved` · `closed` |
| `source` | The connector type that originated the issue (e.g. `pagerduty`, `jira`, `github`) |
| `risk_score` | 0–100 composite risk signal |
An issue moves through statuses as it is investigated and linked to a pattern. Issues with status `in_loop` are actively being analyzed as part of a pattern.
### Pattern
A pattern groups issues that share the same underlying root cause. Causeloop detects patterns automatically by clustering issues on their fingerprint (signal dimensions such as service, error type, time-of-day, and affected team).
| Field | Values |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status` | `emerging` · `active` · `mitigating` · `resolved` — the engine-owned lifecycle state machine |
| `phase` | `emerging` · `active` · `held` · `broken` — a UI-facing projection of `status` plus one piece of real cross-entity state (an open fix-verification window); never a second source of truth |
| `risk_score` | 0–100 aggregate signal |
| `confidence` | 0.0–1.0 model confidence that the grouping is accurate |
| `fingerprint` | Key–value map of the shared signal dimensions |
| `sparkline` | Real per-bucket occurrence-count series over the trailing 30 days; `[]` when the pattern has no dated member issues |
| `recurrence` | Recurrence probability at a fixed 45-day horizon, derived from the pattern's stored hazard fit; omitted entirely (not zero) when the pattern isn't fitted yet |
A pattern transitions to `resolved` when a closure note is recorded and its open member issues stop recurring within the configured proof window.
### Cluster
A cluster is a higher-order grouping of patterns that share structural relationships (common services, overlapping time windows, or shared contributing factors). Clusters appear in the pattern graph view and help you see which patterns belong to the same systemic problem.
Clusters are a byproduct of the engine's Leiden partition stage — recomputed on every `POST /engine/runs`, never via a standalone recompute call. To change membership directly, use a [pin](#pins) rather than editing a cluster.
### Prediction
A prediction is a forward-looking risk signal derived from a pattern's recurrence history.
| Field | Notes |
| ---------------- | ---------------------------------------------------------------------- |
| `probability` | 0.0–1.0 likelihood the pattern recurs within `window_days` |
| `window_days` | Forecast horizon in days |
| `impact` | `critical` / `high` / `medium` / `low` |
| `likely_trigger` | AI-generated description of what will likely cause the next recurrence |
The prediction model is evaluated continuously. You can record feedback (`hit` / `miss` / `prevented`) on each prediction to improve accuracy over time.
### Recommendation
A recommendation is a ranked, actionable remediation tied to one or more patterns.
| Field | Values |
| -------------------------- | ---------------------------------------------------------- |
| `status` | `pending` · `in_progress` · `implemented` · `dismissed` |
| `effort` | `low` / `medium` / `high` |
| `impact` | `high` / `medium` / `quick_win` |
| `rank` | Priority order within the workspace (1 = highest) |
| `expected_loops_prevented` | Model estimate of recurrences eliminated if this fix holds |
Recommendations can be queued for push to your issue tracker (Jira, Linear, GitHub, ServiceNow) via `POST /recommendations/{id}/push`. This requires a connected connector of that tracker type (`409 tracker_not_connected` otherwise); Causeloop does not fabricate a ticket ID or URL — a successful push returns `external_ref: null` until a real tracker integration creates one.
***
## Integration entities
### Connector
A connector is a configured integration with an external tool. Connectors pull issue data into Causeloop on a schedule or respond to inbound webhooks.
Causeloop supports 70+ connector types organized by category:
| Category | Examples |
| ----------------------- | --------------------------------------------- |
| Cloud & Monitoring | Datadog, Dynatrace, New Relic, AWS CloudWatch |
| Productivity & Incident | PagerDuty, Jira, GitHub, Linear, Opsgenie |
| CRM & Support | Salesforce, Zendesk, HubSpot |
| Data | PostgreSQL, Snowflake, BigQuery |
| Security | Okta, CrowdStrike, Splunk |
Each connector has a `status` (`active` / `paused` / `error`), a configurable `poll_interval_seconds`, and a sync run history.
***
## Plan and seat concepts
### Plan
A plan is the subscription tier of an organization: `free`, `starter`, `growth`, or `enterprise`. The plan controls feature flags, rate limits, and which connectors are available.
### Seat
A seat is one active membership slot. The organization's `seats_total` cap limits how many concurrent active memberships a workspace can hold. Suspending a membership frees the seat without deleting the user's data.
***
## Quick reference
| Term | One-line definition |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| Organization | Top-level client account |
| Workspace | Data boundary; all product data lives here |
| User | Global identity (unique email) |
| Membership | User ↔ Workspace link with a role |
| Issue | A single failure event |
| Pattern | A cluster of related issues sharing a root cause |
| Cluster | A grouping of related patterns |
| Prediction | A forward-looking recurrence risk signal, derived from a fitted hazard model |
| Recommendation | A ranked, trackable fix for a pattern with a computed business case |
| Connector | A configured integration that feeds issues in |
| Plan | Subscription tier controlling features and limits |
| Seat | One active membership slot against the org's cap |
| Event | An append-only, content-hashed record — the source of truth issues/patterns are projected from |
| Provenance | `{run_id, manifest_hash, config_versions}` attached to every computed number |
| Review item | An abstained classification result routed to a human instead of a guess |
| Hazard model | The fitted point process (`powerlaw_nhpp_hawkes_v1`) behind a pattern's predictions |
| Pin | A hard constraint on clustering that survives every future engine run |
| Verification | CUSUM-based monitoring that proves a fix's effect before closing the loop |
| Config version | An immutable, hash-identified control-plane document (`rubric`, `cluster`, `hazard`, `rate-card`, `taxonomy`) |
Get from sign-in to your first insights in 10 minutes.
Understand how the platform layers fit together.