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.
Request
This endpoint expects an object.
short_namestringRequired
Source type identifier (e.g., ‘slack’, ‘github’, ‘notion’)
readable_collection_idstringRequired
The readable ID of the collection to add this connection to
namestring or nullOptional4-42 characters
Display name for the connection. If not provided, defaults to ‘{Source Name} Connection’.
descriptionstring or nullOptional<=255 characters
Optional description of what this connection is used for
configmap from strings to any or nullOptional
Source-specific configuration (e.g., repository name, filters)
scheduleobject or nullOptional
Optional sync schedule configuration
sync_immediatelyboolean or nullOptional
Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication)
authenticationobject or nullOptional
Authentication configuration. Type is auto-detected from provided fields.
redirect_urlstring or nullOptional
URL to redirect to after OAuth flow completes (only used for OAuth flows)
Response
Created source connection
idstringformat: "uuid"
Unique identifier of the source connection
organization_idstringformat: "uuid"
Organization this connection belongs to
namestring
Display name of the connection
short_namestring
Source type identifier
readable_collection_idstring
Collection this connection belongs to
statusenum
Current operational status of the connection
created_atstringformat: "date-time"
When the connection was created (ISO 8601)
modified_atstringformat: "date-time"
When the connection was last modified (ISO 8601)
authobject
Authentication status and details
descriptionstring or null
Optional description of the connection's purpose
configmap from strings to any or null
Source-specific configuration values
scheduleobject or null
Sync schedule configuration
syncobject or null
Sync execution history and statistics
sync_idstring or nullformat: "uuid"
ID of the associated sync (internal use)
entitiesobject or null
Summary of synced entities by type
error_categoryenum or null
Error category when status is needs_reauth (e.g. oauth_credentials_expired)
error_messagestring or null
Human-readable error message when status is needs_reauth
provider_settings_urlstring or null
URL to the auth provider’s settings dashboard (for auth_provider errors)
provider_short_namestring or null
Auth provider short_name (e.g. ‘composio’, ‘pipedream’) for display
federated_searchbooleanDefaults to false
Whether this source uses federated (real-time) search instead of syncing
