Appearance
Connectors API
Overview
The Connectors API manages SaaS tool integrations: OAuth flows, sync operations, record queries, webhook ingestion, entity resolution, and admin oversight. All endpoints require authentication (session cookie or API key) and the saas_connectors feature flag unless noted otherwise.
Base path: /api/connectors
Connector catalog
List available connectors
GET /api/connectors/Returns all registered connectors with categories and connection status.
Response
json
{
"connectors": [
{
"id": "rippling",
"display_name": "Rippling",
"category": "hris",
"description": "Sync employee directory, departments, and teams",
"supported_entities": ["employee", "company"],
"supports_webhooks": true,
"icon_url": "/connector-logos/rippling.svg",
"connected": true,
"connection_id": "conn_abc123"
},
{
"id": "merge_hris",
"display_name": "Merge HRIS",
"category": "hris",
"description": "Connect 50+ HRIS platforms via unified API",
"supported_entities": ["employee", "team", "employment", "location"],
"supports_webhooks": false,
"icon_url": "/connector-logos/merge.svg",
"connected": false,
"connection_id": null
}
]
}OAuth flow
Start OAuth flow
GET /api/connectors/{connector_id}/connectRedirects the user to the SaaS provider’s OAuth authorization page. A cryptographic state parameter is generated and stored server-side (5-minute TTL) for CSRF protection.
| Parameter | Type | Description |
|---|---|---|
connector_id | path | Connector identifier (for example, rippling) |
Response
302 Redirect to the provider’s OAuth consent page.
OAuth callback
GET /api/connectors/{connector_id}/callbackHandles the OAuth callback from the SaaS provider. Exchanges the authorization code for access and refresh tokens, encrypts them with AES-256-GCM, and creates the connection.
| Parameter | Type | Description |
|---|---|---|
connector_id | path | Connector identifier |
code | query | Authorization code from provider |
state | query | CSRF state token (validated server-side) |
Response
HTML page that sends postMessage to the opener window and auto-closes.
Connection management
List connections
GET /api/connectors/connectionsReturns the authenticated user’s active connections.
Response
json
{
"connections": [
{
"id": "conn_abc123",
"connector_id": "rippling",
"status": "active",
"health_status": "healthy",
"provider_account_name": "Acme Corp",
"last_synced_at": "2026-03-29T10:00:00Z",
"record_count": 127,
"visibility_scope": "cloud",
"visibility_scope_id": null,
"created_at": "2026-03-28T14:30:00Z"
}
]
}Connection detail
GET /api/connectors/connections/{id}Returns full detail for a single connection, including health information.
| Parameter | Type | Description |
|---|---|---|
id | path | Connection ID |
Response
json
{
"id": "conn_abc123",
"connector_id": "rippling",
"display_name": "Rippling",
"status": "active",
"health_status": "healthy",
"health_checked_at": "2026-03-29T10:15:00Z",
"provider_account_name": "Acme Corp",
"last_synced_at": "2026-03-29T10:00:00Z",
"record_count": 127,
"visibility_scope": "cloud",
"visibility_scope_id": null,
"consent_accepted_at": "2026-03-28T14:30:00Z",
"created_at": "2026-03-28T14:30:00Z",
"updated_at": "2026-03-29T10:00:00Z"
}Disconnect
DELETE /api/connectors/connections/{id}Revokes the connection and cascade-deletes all associated records and memories.
| Parameter | Type | Description |
|---|---|---|
id | path | Connection ID |
Response
json
{
"status": "revoked",
"records_deleted": 127,
"memories_deleted": 127,
"webhooks_disabled": 1
}Set visibility scope
PUT /api/connectors/connections/{id}/visibilityAdmin-only. Sets who can see data from this connection.
| Parameter | Type | Description |
|---|---|---|
id | path | Connection ID |
Request
json
{
"visibility_scope": "group",
"visibility_scope_id": "grp_leadership"
}| Field | Type | Required | Description |
|---|---|---|---|
visibility_scope | string | Yes | cloud, group, or user |
visibility_scope_id | string | When scope is group | Group ID for group-restricted scope |
Response
json
{
"id": "conn_abc123",
"visibility_scope": "group",
"visibility_scope_id": "grp_leadership",
"updated_at": "2026-03-29T11:00:00Z"
}Sync operations
Trigger sync
POST /api/connectors/connections/{id}/syncTriggers a manual sync for the connection. Returns immediately; sync runs as a background task.
| Parameter | Type | Description |
|---|---|---|
id | path | Connection ID |
Response
json
{
"sync_job_id": "sync_xyz789",
"status": "pending",
"trigger": "manual",
"created_at": "2026-03-29T11:05:00Z"
}List sync jobs
GET /api/connectors/connections/{id}/sync-jobsReturns sync job history for a connection.
| Parameter | Type | Description |
|---|---|---|
id | path | Connection ID |
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | int | 20 | Maximum results |
offset | int | 0 | Pagination offset |
Response
json
{
"sync_jobs": [
{
"id": "sync_xyz789",
"status": "completed",
"trigger": "scheduled",
"entity_types": "employee",
"records_synced": 127,
"records_total": 127,
"errors": null,
"started_at": "2026-03-29T10:00:00Z",
"completed_at": "2026-03-29T10:00:08Z",
"duration_ms": 8200
}
],
"total": 15
}Push to memory
POST /api/connectors/connections/{id}/memory-syncPushes synced records through the MemoryBridge to create or update AI memories. Usually triggered automatically after sync; this endpoint allows manual re-bridging.
| Parameter | Type | Description |
|---|---|---|
id | path | Connection ID |
Response
json
{
"memories_created": 12,
"memories_updated": 115,
"memories_unchanged": 0,
"pii_fields_filtered": 889
}Record queries
Query synced records
GET /api/connectors/connections/{id}/recordsReturns synced records for a connection. Respects visibility scope.
| Parameter | Type | Description |
|---|---|---|
id | path | Connection ID |
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
entity_type | string | all | Filter by entity type (for example, employee) |
search | string | — | Search by name or email |
limit | int | 50 | Maximum results |
offset | int | 0 | Pagination offset |
Response
json
{
"records": [
{
"id": "rec_001",
"entity_type": "employee",
"external_id": "emp_12345",
"record_kind": "data",
"data": {
"name": "Alice Smith",
"email": "alice@acme.com",
"department": "Engineering",
"title": "Senior Engineer",
"team": "Platform",
"manager": "Bob Jones",
"work_location": "San Francisco",
"employment_type": "Full-time",
"start_date": "2024-01-15",
"status": "Active"
},
"synced_at": "2026-03-29T10:00:05Z",
"memory_id": "mem_abc123"
}
],
"total": 127
}Webhooks
Inbound webhook
POST /api/connectors/webhooks/{connector_id}/{webhook_secret}Public endpoint — no cookie or API key required. Authenticated via connector-specific signature verification on the request headers and body.
This is the URL that SaaS tools POST events to. Each connection gets a unique webhook_secret in the URL.
The endpoint:
- Validates the connector-specific signature (for example, Rippling HMAC).
- Checks timestamp freshness (rejects payloads older than 5 minutes when available).
- Parses events into normalized records.
- Upserts records and triggers MemoryBridge.
| Parameter | Type | Description |
|---|---|---|
connector_id | path | Connector identifier |
webhook_secret | path | Per-connection webhook secret |
Response
200 OK with:
json
{
"status": "accepted",
"records_upserted": 1
}Rate limit: 100 requests per minute per webhook_secret. Excess traffic returns 429 Too Many Requests.
Entity resolution
Requires the saas_connector_entities feature flag for endpoints in this section.
List resolved entities
GET /api/connectors/entitiesReturns cross-connector resolved entities for the organization.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
entity_type | string | all | person, company, or team |
search | string | — | Search by name or identifier |
limit | int | 50 | Maximum results |
Response
json
{
"entities": [
{
"id": "ent_alice",
"entity_type": "person",
"primary_identifier": "alice@acme.com",
"display_name": "Alice Smith",
"source_count": 2,
"sources": ["rippling", "salesforce"],
"updated_at": "2026-03-29T10:00:05Z"
}
],
"total": 89
}Entity profile
GET /api/connectors/entities/{id}Returns the unified profile for a resolved entity with merged fields. Use Entity source records for per-connector rows.
| Parameter | Type | Description |
|---|---|---|
id | path | Entity ID |
Response
json
{
"id": "ent_alice",
"entity_type": "person",
"primary_identifier": "alice@acme.com",
"display_name": "Alice Smith",
"merged_data": {
"name": "Alice Smith",
"email": "alice@acme.com",
"department": "Engineering",
"title": "Senior Engineer",
"team": "Platform",
"work_location": "San Francisco"
},
"source_count": 2,
"first_seen_at": "2026-03-28T14:30:00Z",
"updated_at": "2026-03-29T10:00:05Z"
}Entity source records
GET /api/connectors/entities/{id}/recordsReturns all source records that resolved to this entity.
| Parameter | Type | Description |
|---|---|---|
id | path | Entity ID |
Response
json
{
"records": [
{
"id": "rec_001",
"connector_id": "rippling",
"entity_type": "employee",
"external_id": "emp_12345",
"data": {
"name": "Alice Smith",
"department": "Engineering"
},
"synced_at": "2026-03-29T10:00:05Z"
}
]
}Admin endpoints
Admin-only unless noted. Operates across the whole organization.
All organization connections
GET /api/connectors/admin/connectionsReturns every connection in the organization. Response shape matches List connections, with user_id and user_email on each item.
Response
json
{
"connections": [
{
"id": "conn_abc123",
"connector_id": "rippling",
"status": "active",
"health_status": "healthy",
"provider_account_name": "Acme Corp",
"last_synced_at": "2026-03-29T10:00:00Z",
"record_count": 127,
"visibility_scope": "cloud",
"visibility_scope_id": null,
"created_at": "2026-03-28T14:30:00Z",
"user_id": "usr_admin01",
"user_email": "admin@acme.com"
},
{
"id": "conn_def456",
"connector_id": "merge_hris",
"status": "active",
"health_status": "warning",
"provider_account_name": "Acme Corp — BambooHR",
"last_synced_at": "2026-03-28T22:00:00Z",
"record_count": 412,
"visibility_scope": "group",
"visibility_scope_id": "grp_hr_ops",
"created_at": "2026-03-20T09:00:00Z",
"user_id": "usr_hr_lead",
"user_email": "hr.lead@acme.com"
}
]
}Organization health overview
GET /api/connectors/admin/healthReturns a health summary for all organization connections.
Response
json
{
"total_connections": 3,
"healthy": 2,
"warning": 1,
"error": 0,
"expired": 0,
"connections": [
{
"id": "conn_abc123",
"connector_id": "rippling",
"health_status": "healthy",
"health_checked_at": "2026-03-29T10:15:00Z",
"provider_account_name": "Acme Corp",
"user_email": "admin@acme.com"
}
]
}Authentication
All endpoints except the inbound webhook require authentication via session cookie or API key header:
Authorization: Bearer <api_key>The inbound webhook endpoint authenticates via connector-specific signature verification on the request body (and headers, where applicable).
Feature flags
| Flag | Required for | Tier |
|---|---|---|
saas_connectors | All connector endpoints | Personal+ |
saas_connector_webhooks | Webhook processing | Business+ |
saas_connector_actions | Action execution | Business+ |
saas_connector_entities | Entity resolution endpoints | Business+ |
saas_connector_unified_api | Merge and unified API connectors | Enterprise |
Error responses
Standard error format:
json
{
"detail": "Connection not found",
"status_code": 404
}| Status | Meaning |
|---|---|
| 400 | Invalid request parameters |
| 401 | Not authenticated |
| 403 | Insufficient permissions or feature unavailable for tier |
| 404 | Connection or entity not found |
| 429 | Rate limit exceeded (webhooks) |
| 500 | Internal server error |