Sign in

v50

latestOpenAPI 3.1.0raw.githubusercontent.com2026-03-222763184.3 KB
source-connections

Create Source Connection

Create a new source connection to sync data from an external source.

The authentication method determines the creation flow:

  • Direct: Provide credentials (API key, token) directly. Connection is created immediately.
  • OAuth Browser: Returns a connection with an auth_url to redirect users for authentication.
  • OAuth Token: Provide an existing OAuth token. Connection is created immediately.
  • Auth Provider: Use a pre-configured auth provider (e.g., Composio, Pipedream).

After successful authentication, data sync can begin automatically or on-demand.

post/source-connections

Request body

namestring nullable

Display name for the connection. If not provided, defaults to '{Source Name} Connection'.

short_namestring required

Source type identifier (e.g., 'slack', 'github', 'notion')

readable_collection_idstring required

The readable ID of the collection to add this connection to

descriptionstring nullable

Optional description of what this connection is used for

configobject nullable

Source-specific configuration (e.g., repository name, filters)

sync_immediatelyboolean nullable

Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication)

redirect_urlstring nullable

URL to redirect to after OAuth flow completes (only used for OAuth flows)

Example request

{
  "summary": "Direct auth (API key)",
  "value": {
    "authentication": {
      "credentials": {
        "personal_access_token": "ghp_xxxxxxxxxxxx"
      }
    },
    "config": {
      "branch": "main",
      "repo_name": "company/docs"
    },
    "name": "GitHub Docs Repo",
    "readable_collection_id": "documentation-ab123",
    "short_name": "github"
  }
}

Response

Created source connection

idstring uuid required

Unique identifier of the source connection

organization_idstring uuid required

Organization this connection belongs to

namestring required

Display name of the connection

descriptionstring nullable

Optional description of the connection's purpose

short_namestring required

Source type identifier

readable_collection_idstring required

Collection this connection belongs to

status'active' | 'pending_auth' | 'syncing' | 'error' | 'inactive' | 'pending_sync' required

Source connection status enum - represents overall connection state.

created_atstring date-time required

When the connection was created (ISO 8601)

modified_atstring date-time required

When the connection was last modified (ISO 8601)

configobject nullable

Source-specific configuration values

sync_idstring uuid nullable

ID of the associated sync (internal use)

federated_searchboolean

Whether this source uses federated (real-time) search instead of syncing

Example response

{
  "auth": {
    "authenticated": true,
    "authenticated_at": "2024-03-15T09:30:00Z",
    "method": "direct"
  },
  "config": {
    "branch": "main",
    "repo_name": "company/docs"
  },
  "created_at": "2024-03-15T09:30:00Z",
  "description": "Main documentation repository",
  "entities": {
    "by_type": {
      "file": {
        "count": 1250
      }
    },
    "total_entities": 1250
  },
  "federated_search": false,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "modified_at": "2024-03-15T14:22:15Z",
  "name": "GitHub Docs Repo",
  "readable_collection_id": "documentation-ab123",
  "schedule": {
    "cron": "0 */6 * * *",
    "next_run": "2024-03-15T18:00:00Z"
  },
  "short_name": "github",
  "status": "ACTIVE",
  "sync": {
    "failed_runs": 1,
    "last_job": {
      "completed_at": "2024-03-15T12:05:32Z",
      "duration_seconds": 332,
      "entities_inserted": 45,
      "entities_updated": 12,
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "started_at": "2024-03-15T12:00:00Z",
      "status": "COMPLETED"
    },
    "successful_runs": 14,
    "total_runs": 15
  }
}