API ReferenceSource Connections

Create Source Connection

Create a new source connection to sync data into your collection.

This endpoint only works for sources that do not use OAuth2.0. Sources that do use OAuth2.0 like Google Drive, Slack, or HubSpot must be connected through the UI where you can complete the OAuth consent flow.

Credentials for a source have to be provided using the auth_fields field. Currently, it is not automatically checked if the provided credentials are valid. If they are not valid, the data synchronization will fail.

Check the documentation of a specific source (for example Github) to see what kind of authentication is used.

Headers

x-api-keystringRequired

Request

This endpoint expects an object.
namestringRequired>=4 characters<=42 characters

Human-readable name for the source connection. This helps you identify the connection in the UI and should clearly describe what data it connects to.

short_namestringRequired
Technical identifier of the source type that determines which connector to use for data synchronization.
descriptionstring or nullOptional
Optional detailed description of what this source connection provides. Use this to document the purpose, data types, or any special considerations for this connection.
config_fieldsobject or nullOptional

Source-specific configuration parameters required for data extraction. These vary by source type and control how data is retrieved (e.g., database queries, API filters, file paths). Check the documentation of a specific source (for example Github) to see what is required.

collectionstring or nullOptional
Readable ID of the collection where synced data will be stored. If not provided, a new collection will be automatically created.
cron_schedulestring or nullOptional

Cron expression for automatic data synchronization schedule. If not provided, data will only sync when manually triggered. Use standard cron format: minute hour day month weekday.

auth_fieldsobject or nullOptional

Authentication credentials required to access the data source. The required fields vary by source type. Check the documentation of a specific source (for example Github) to see what is required.

auth_providerstring or nullOptional

Unique readable ID of a connected auth provider to use for authentication instead of providing auth_fields directly. When specified, credentials for the source will be obtained and refreshed automatically by Airweave interaction with the auth provider. To see which auth providers are supported and learn more about how to use them, check this page.

auth_provider_configobject or nullOptional

Configuration for the auth provider when using auth_provider field. Required fields vary by auth provider. For Composio, use auth_config_id and account_id to specify which integration and account from Composio you want to use to connect to the source.

sync_immediatelybooleanOptionalDefaults to true
Whether to start an initial data synchronization immediately after creating the connection.

Response

Successful Response
namestring>=1 character<=64 characters

Human-readable display name for the source connection. This helps you identify the connection in the UI and should clearly describe what data it connects to (e.g., ‘Production Stripe Account’, ‘Customer Support Database’).

short_namestring

Technical identifier of the source type (e.g., ‘github’, ‘stripe’, ‘postgresql’, ‘slack’). This determines which connector Airweave uses to sync data.

idstringformat: "uuid"
Unique system identifier for this source connection. This UUID is generated automatically and used for API operations.
organization_idstringformat: "uuid"
Identifier of the organization that owns this source connection. Source connections are isolated per organization.
created_atstringformat: "date-time"

Timestamp when the source connection was created (ISO 8601 format).

modified_atstringformat: "date-time"

Timestamp when the source connection was last modified (ISO 8601 format).

collectionstring
Readable ID of the collection where this source connection syncs its data. This creates the link between your data source and searchable content.
descriptionstring or null<=255 characters
Optional additional context about the data this connection provides. Use this to document the purpose, data types, or any special considerations for this connection.
config_fieldsobject or null

Source-specific configuration options that control data retrieval behavior. These vary by source type and control how data is retrieved (e.g., database queries, API filters, file paths). Check the documentation of a specific source (for example Github) to see what is required.

white_label_idstring or nullformat: "uuid"
Identifier for custom OAuth integrations. Only present for connections created through white label OAuth flows.
auth_providerstring or null
Readable ID of the auth provider used to create this connection. Present only if the connection was created through an auth provider.
auth_provider_configmap from strings to any or null
Configuration used with the auth provider to create this connection. Present only if the connection was created through an auth provider.
sync_idstring or nullformat: "uuid"
Internal identifier for the sync configuration associated with this source connection. Managed automatically by the system.
connection_idstring or nullformat: "uuid"
Internal identifier for the underlying connection object that manages authentication and configuration.
created_by_emailstring or nullformat: "email"
Email address of the user who created this source connection.
modified_by_emailstring or nullformat: "email"
Email address of the user who last modified this source connection.
auth_fieldsobject or string or null

Authentication credentials for the data source. Returns ’********’ by default for security.

statusenum or null

Current operational status of the source connection:
• active: Connection is healthy and ready for data synchronization
• in_progress: Currently syncing data from the source
• failing: Recent sync attempts have failed and require attention

Allowed values:
latest_sync_job_statusenum or null

Status of the most recent data synchronization job:
• completed: Last sync finished successfully
• failed: Last sync encountered errors
• in_progress: Currently running a sync job
• pending: Sync job is queued and waiting to start

latest_sync_job_idstring or nullformat: "uuid"
Unique identifier of the most recent sync job. Use this to track sync progress or retrieve detailed job information.
latest_sync_job_started_atstring or nullformat: "date-time"

Timestamp when the most recent sync job started (ISO 8601 format).

latest_sync_job_completed_atstring or nullformat: "date-time"

Timestamp when the most recent sync job completed (ISO 8601 format). Null if the job is still running or failed.

latest_sync_job_errorstring or null
Error message from the most recent sync job if it failed. Use this to diagnose and resolve sync issues.
cron_schedulestring or null
Cron expression defining when automatic data synchronization occurs. Null if automatic syncing is disabled and syncs must be triggered manually.
next_scheduled_runstring or nullformat: "date-time"

Timestamp when the next automatic sync is scheduled to run (ISO 8601 format). Null if no automatic schedule is configured.

Errors