You can connect a new source in about two minutes from the Causeloop UI. For automation or CI/CD pipelines, the same flow is available via the API.
Connect via the UI
Open the Integrations page
Go to Settings → Integrations in the sidebar, or navigate directly to https://app.causeloop.ai/integrations. You’ll see the connector catalog grouped by category.
Choose a connector
Click the connector you want to add. The detail panel shows what the connector ingests, what permissions it needs, and whether it uses OAuth or an API key.
Name your connection
Give the connector an optional display name (e.g. “Production PagerDuty”). This is how it appears in sync logs and webhook filters.
Authenticate
OAuth connectors — click Authorize. Causeloop opens the provider’s login page in a new window. Sign in and grant the requested scopes. You’re redirected back to Causeloop when complete.API key connectors — paste your API key (or service account token) into the credentials field and click Save.
Test the connection
Causeloop automatically tests the connection after saving. A green checkmark means the credentials are valid and the connector can reach the provider. If the test fails, double-check the credentials and retry.
Configure the sync schedule (optional)
By default, connectors sync every 30 minutes. Open the Schedule tab to change the frequency or set a custom cron expression. You can also trigger an immediate sync or a historical backfill from this panel.
Start syncing
The connector is now active. Causeloop starts an initial backfill (configurable window) and then switches to your chosen schedule. You’ll see sync runs appear in the Sync History tab within a few minutes.
Connect via the API
1. Look up the connector type
curl https://api.causeloop.ai/v1/connector-catalog/jira \
-H "Authorization: Bearer $TOKEN"
type and oauth fields in the response — they determine your next step.
2. Create the connector record
curl -X POST https://api.causeloop.ai/v1/connectors \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "jira",
"display_name": "Production Jira",
"credentials": {}
}'
id (e.g. con_01hx4k2m9p). Save it — you’ll need it for the next step.
3a. OAuth connectors — start the authorization flow
curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/oauth/start \
-H "Authorization: Bearer $TOKEN"
{
"authorize_url": "https://auth.atlassian.com/authorize?...",
"state": "oast_01hx5c3d4e",
"expires_at": "2026-06-14T10:10:00Z"
}
authorize_url. The state token expires in 10 minutes — the user must complete authorization within that window.
3b. Handle the OAuth callback
After the user grants access, the provider redirects to:
https://api.causeloop.ai/v1/connectors/oauth/callback?code=AUTH_CODE&state=oast_01hx5c3d4e
connected. You don’t need to call this endpoint yourself.
When building your own OAuth UX, configure your provider app’s Redirect URI to https://api.causeloop.ai/v1/connectors/oauth/callback. This is the only URI the callback endpoint accepts.
3c. API key connectors — supply credentials directly
curl -X PATCH https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"credentials": {
"api_key": "your-api-key-here"
}
}'
4. Test the connection
curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/test \
-H "Authorization: Bearer $TOKEN"
200 response with "success": true confirms the connector can reach the provider.
5. Trigger a sync
curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/sync \
-H "Authorization: Bearer $TOKEN"
202 Accepted with a sync_run_id. Poll GET /v1/connectors/{id}/sync-runs/{run_id} to track progress.
OAuth flow in detail
For OAuth connectors, Causeloop implements a standard 3-leg authorization code flow:
Your app / UI Causeloop Provider
│ │ │
│ POST /oauth/start │ │
│ ──────────────────────────►│ │
│ {authorize_url, state} │ │
│ ◄──────────────────────────│ │
│ │ │
│ Redirect user to │ │
│ authorize_url ────────────────────────────────────────► │
│ │ │
│ │ ?code=XXX&state=YYY │
│ │ ◄────────────────────────────│
│ (callback handled by Causeloop) │
│ │ exchange code for tokens │
│ │ ─────────────────────────── ►│
│ │ {access_token, refresh_token}│
│ │ ◄────────────────────────────│
│ │ connector status → connected │
│ ◄──────────────────────────│ │
Managing schedule and backfill
Set a custom sync schedule
curl -X PUT https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/schedule \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"cron": "0 */2 * * *",
"timezone": "America/New_York"
}'
Run a historical backfill
curl -X POST https://api.causeloop.ai/v1/connectors/con_01hx4k2m9p/backfill \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": "2026-01-01T00:00:00Z",
"to": "2026-06-01T00:00:00Z"
}'
Connector status reference
| Status | Meaning |
|---|
pending | Created but not yet authorized or tested |
connected | Active and syncing normally |
paused | Manually paused — syncs will not run |
error | Last sync failed — check sync history for details |
oauth_expired | OAuth token expired and could not be refreshed — re-authorize |
Subscribe to connector.sync.failed events via an outbound webhook to get notified immediately when a connector goes into an error state. 
