Skip to main content
This guide walks you from zero to three real API calls. You’ll exchange a Clerk session JWT for a Causeloop token, then list issues, fetch a pattern, and create a new issue.
You need a Causeloop workspace and a Clerk session JWT. If you’re testing locally, run the backend with USE_MOCK=1 — the exchange endpoint accepts any non-empty subject_token and returns a valid scoped JWT backed by seed data.
1

Exchange your Clerk session JWT for a Causeloop token

Call POST /v1/auth/exchange with your Clerk session JWT.
curl -X POST https://api.causeloop.ai/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{"subject_token": "<your_clerk_session_jwt>"}'
You’ll receive a response like:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "clp_refresh_...",
  "token_type": "bearer",
  "expires_in": 259200,
  "scope": "issues:read issues:write patterns:read ...",
  "workspace_id": "ws_01abc123"
}
Save the access_token. It’s valid for 72 hours. Set it as an environment variable for the next steps:
export CAUSELOOP_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
2

List your issues

GET /v1/issues returns a cursor-paginated list of issues in your workspace, newest first.
curl https://api.causeloop.ai/v1/issues \
  -H "Authorization: Bearer $CAUSELOOP_TOKEN"
Example response
{
  "data": [
    {
      "id": "iss_01abc123",
      "title": "Payment gateway timeout on checkout",
      "status": "open",
      "severity": "high",
      "pattern_id": "pat_01xyz789",
      "created_at": "2024-01-15T09:00:00Z"
    }
  ],
  "page": {
    "next_cursor": "eyJvZmZzZXQiOiAyNX0",
    "has_more": true,
    "total": 87
  }
}
To page through results, pass cursor=<next_cursor> on the next request. See Pagination & Filtering for full details.
3

Fetch a pattern

Patterns are clusters of related issues. Use the pattern_id from an issue (or list all patterns) to get details.
curl https://api.causeloop.ai/v1/patterns/pat_01xyz789 \
  -H "Authorization: Bearer $CAUSELOOP_TOKEN"
Example response
{
  "id": "pat_01xyz789",
  "name": "Payment gateway timeout under load",
  "status": "active",
  "risk_score": 82,
  "issue_count": 14,
  "last_seen_at": "2024-01-15T09:00:00Z",
  "fingerprint": {
    "domain": "payments",
    "root_cause": "third_party_timeout"
  }
}
4

Next steps

Pagination & Filtering

Page through large result sets and apply filters and sorting.

Real-time events

Subscribe to live issue and pattern updates via WebSocket.

Rate limits

Understand limits and implement retry logic.

Error handling

Handle errors consistently across all endpoints.