> ## 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.

# API Overview

> Base URLs, versioning, content types, the interactive explorer, and a map of the auto-generated endpoint reference.

The Causeloop REST API gives you programmatic access to every resource in the platform — issues, patterns, predictions, recommendations, connectors, and more. All resources live inside a **workspace**, and every authenticated request is automatically scoped to your workspace.

## Base URLs

| Environment       | Base URL                   |
| ----------------- | -------------------------- |
| Production        | `https://api.causeloop.ai` |
| Local development | `http://localhost:4000`    |

<Note>
  All REST endpoints are prefixed with `/v1`. A request to list issues is `GET https://api.causeloop.ai/v1/issues`.
</Note>

## Versioning

The current API version is **v1**, expressed as a URL path prefix (`/v1/…`). Breaking changes will be released under a new prefix (e.g. `/v2/…`) with a migration guide and a deprecation period. Non-breaking additions — new fields, new optional query parameters, new event types — are made to the current version without a version bump.

## Content type

All request and response bodies are JSON. Set the `Content-Type` header on mutating requests:

```http theme={null}
Content-Type: application/json
```

Responses always include `Content-Type: application/json`.

## Interactive API explorer

Causeloop ships an interactive OpenAPI explorer at:

| Environment | URL                             |
| ----------- | ------------------------------- |
| Production  | `https://api.causeloop.ai/docs` |
| Local       | `http://localhost:4000/docs`    |

The raw OpenAPI schema is available at `/openapi.json`. You can import it into Postman, Insomnia, or any OpenAPI-compatible client.

## Authentication overview

Every API request must carry a Bearer JWT in the `Authorization` header:

```http theme={null}
Authorization: Bearer <token>
```

The typical flow for human users is:

1. Authenticate with WorkOS AuthKit in your frontend.
2. Exchange the WorkOS access token for a Causeloop Bearer token at `POST /v1/auth/exchange`.
3. Send the Causeloop token in the `Authorization` header.

Machine-to-machine callers use **service accounts** with long-lived tokens instead.

See the full [Authentication guide](/api-reference/authentication) for details, including service accounts, MFA, SSO, and SCIM provisioning.

## How the endpoint reference is organized

The auto-generated reference pages, linked in the sidebar, are organized by resource. The full surface is one deterministic pipeline — event log in, engine run, provenance-stamped outputs out — so several of these resource groups are new in this version of the API.

<CardGroup cols={2}>
  <Card title="Events" icon="timeline">
    The append-only event log. Issue and pattern rows are projections rebuilt from it. `GET /workspaces/current/events` is the machine-replayable feed.
  </Card>

  <Card title="Issues" icon="triangle-exclamation">
    Create, list, retrieve, update, and close issues. `narrative` + `occurred_at` drive the pipeline; `GET /issues/{id}/events` exposes the per-issue event history.
  </Card>

  <Card title="Config Registry" icon="sliders">
    `/configs/{kind}` — immutable, hash-versioned control-plane documents (`rubric`, `cluster`, `hazard`, `rate-card`, `taxonomy`). Replaces `/rubric`.
  </Card>

  <Card title="Engine Runs" icon="gears">
    `POST /engine/runs` drives the full 10-stage pipeline. `GET /engine/runs/{id}` returns the run manifest and stability report; `POST /engine/runs/{id}/replay` is the determinism check.
  </Card>

  <Card title="Review Queue" icon="clipboard-check">
    `/review-queue` — abstained extraction, root-cause, and criticality items routed to a human instead of a guess.
  </Card>

  <Card title="Patterns & Hazard" icon="diagram-project">
    Clusters of related issues (`/patterns`), root-cause rollups, financials, and the fitted hazard model (`/patterns/{id}/hazard`) with forecast, crest alerts, and counterfactuals.
  </Card>

  <Card title="Predictions & Backtests" icon="chart-line">
    Projections of fitted hazards (`p_recurrence`, `T̂_R`), plus `/predictions/backtests` for rolling-origin accuracy — no fabricated metrics.
  </Card>

  <Card title="Recommendations & Verification" icon="lightbulb">
    Fix recommendations with a computed (never client-supplied) business case, plus `/recommendations/{id}/verification` — the CUSUM-based proof that a fix held.
  </Card>

  <Card title="Reports" icon="file-chart-column">
    Async report generation over a deterministic facts JSON. A narrated numeral that can't be traced to the facts fails the run (`report_facts_mismatch`), never renders wrong.
  </Card>

  <Card title="Connectors" icon="plug">
    Data source connections — create, configure, test, and sync.
  </Card>

  <Card title="Sources" icon="database">
    `/sources` and `/sources/summary` — real per-source ingest stats (connectors and ad-hoc ingest channels alike), computed from stored issue data.
  </Card>

  <Card title="Users & Members" icon="users">
    Workspace membership, roles, invitations.
  </Card>

  <Card title="Service Accounts" icon="robot">
    Machine identities for automation and integrations.
  </Card>
</CardGroup>

## Your first request

Once you have a token (see [Authentication](/api-reference/authentication)), list your workspace's issues:

```bash theme={null}
curl https://api.causeloop.ai/v1/issues \
  -H "Authorization: Bearer <token>"
```

You'll get back a paginated response:

```json theme={null}
{
  "data": [...],
  "page": {
    "next_cursor": "eyJvZmZzZXQiOiAyNX0",
    "has_more": true,
    "total": 142
  }
}
```

Ready to go deeper? Follow the [Quickstart](/api-reference/quickstart) to get a token and make your first three calls in under five minutes.