Skip to navigation
API ReferenceSource 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.

Authentication

x-api-keystring
API Key authentication via header

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 nullOptional
Optional description of the connection's purpose
configmap from strings to any or nullOptional

Source-specific configuration values

scheduleobject or nullOptional
Sync schedule configuration
syncobject or nullOptional
Sync execution history and statistics
sync_idstring or nullOptionalformat: "uuid"

ID of the associated sync (internal use)

entitiesobject or nullOptional
Summary of synced entities by type
error_categoryenum or nullOptional

Error category when status is needs_reauth (e.g. oauth_credentials_expired)

error_messagestring or nullOptional

Human-readable error message when status is needs_reauth

provider_settings_urlstring or nullOptional

URL to the auth provider's settings dashboard (for auth_provider errors)

provider_short_namestring or nullOptional

Auth provider short_name (e.g. 'composio', 'pipedream') for display

Errors

422
Unprocessable Entity Error
429
Too Many Requests Error