API Overview - Causeloop

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`

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

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:

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:

Authorization: Bearer <token>

The typical flow for human users is:

Authenticate with WorkOS AuthKit in your frontend.
Exchange the WorkOS access token for a Causeloop Bearer token at POST /v1/auth/exchange.
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 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.

Events

The append-only event log. Issue and pattern rows are projections rebuilt from it. GET /workspaces/current/events is the machine-replayable feed.

Issues

Create, list, retrieve, update, and close issues. narrative + occurred_at drive the pipeline; GET /issues/{id}/events exposes the per-issue event history.

Config Registry

/configs/{kind} — immutable, hash-versioned control-plane documents (rubric, cluster, hazard, rate-card, taxonomy). Replaces /rubric.

Engine Runs

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.

Review Queue

/review-queue — abstained extraction, root-cause, and criticality items routed to a human instead of a guess.

Patterns & Hazard

Clusters of related issues (/patterns), root-cause rollups, financials, and the fitted hazard model (/patterns/{id}/hazard) with forecast, crest alerts, and counterfactuals.

Predictions & Backtests

Projections of fitted hazards (p_recurrence, T̂_R), plus /predictions/backtests for rolling-origin accuracy — no fabricated metrics.

Recommendations & Verification

Fix recommendations with a computed (never client-supplied) business case, plus /recommendations/{id}/verification — the CUSUM-based proof that a fix held.

Reports

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.

Connectors

Data source connections — create, configure, test, and sync.

Sources

/sources and /sources/summary — real per-source ingest stats (connectors and ad-hoc ingest channels alike), computed from stored issue data.

Users & Members

Workspace membership, roles, invitations.

Service Accounts

Machine identities for automation and integrations.

Your first request

Once you have a token (see Authentication), list your workspace’s issues:

curl https://api.causeloop.ai/v1/issues \
  -H "Authorization: Bearer <token>"

You’ll get back a paginated response:

{
  "data": [...],
  "page": {
    "next_cursor": "eyJvZmZzZXQiOiAyNX0",
    "has_more": true,
    "total": 142
  }
}

Ready to go deeper? Follow the Quickstart to get a token and make your first three calls in under five minutes.

​Base URLs

​Versioning

​Content type

​Interactive API explorer

​Authentication overview

​How the endpoint reference is organized

Events

Issues

Config Registry

Engine Runs

Review Queue

Patterns & Hazard

Predictions & Backtests

Recommendations & Verification

Reports

Connectors

Sources

Users & Members

Service Accounts

​Your first request

Base URLs

Versioning

Content type

Interactive API explorer

Authentication overview

How the endpoint reference is organized

Your first request