---
title: "Create Source Connection"
method: POST
path: "/source-connections"
tags: ["source-connections"]
---

# Create Source Connection

`POST /source-connections`

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 body

- SourceConnectionCreate — Create a source connection with authentication configuration. Source connections link a data source (e.g., GitHub, Slack) to a collection. The authentication method determines how credentials are provided and whether the connection is created immediately or requires an OAuth flow.
  - `name` string, nullable — Display name for the connection. If not provided, defaults to '{Source Name} Connection'.
  - `short_name` string, required — Source type identifier (e.g., 'slack', 'github', 'notion')
  - `readable_collection_id` string, required — The readable ID of the collection to add this connection to
  - `description` string, nullable — Optional description of what this connection is used for
  - `config` object, nullable — Source-specific configuration (e.g., repository name, filters)
  - `schedule` ScheduleConfig — Schedule configuration for syncs.
    - `cron` string, nullable — Cron expression for scheduled syncs
    - `continuous` boolean — Enable continuous sync mode
    - `cursor_field` string, nullable — Field for incremental sync
  - `sync_immediately` boolean, nullable — Run initial sync after creation. Defaults to True for direct/token/auth_provider, False for OAuth browser/BYOC flows (which sync after authentication)
  - `authentication` union — Authentication configuration. Type is auto-detected from provided fields.
    - DirectAuthentication — Direct authentication with API keys or passwords.
      - `credentials` object, required — Authentication credentials
    - OAuthTokenAuthentication — OAuth authentication with pre-obtained token.
      - `access_token` string, required — OAuth access token
      - `refresh_token` string, nullable — OAuth refresh token
      - `expires_at` string, date-time, nullable — Token expiry time
    - OAuthBrowserAuthentication — OAuth authentication via browser flow. Supports both OAuth2 and OAuth1 BYOC (Bring Your Own Client): - OAuth2 BYOC: Provide client_id + client_secret - OAuth1 BYOC: Provide consumer_key + consumer_secret
      - `redirect_uri` string, nullable — OAuth redirect URI
      - `client_id` string, nullable — OAuth2 client ID (for custom apps)
      - `client_secret` string, nullable — OAuth2 client secret (for custom apps)
      - `consumer_key` string, nullable — OAuth1 consumer key (for custom apps)
      - `consumer_secret` string, nullable — OAuth1 consumer secret (for custom apps)
    - AuthProviderAuthentication — Authentication via external provider.
      - `provider_readable_id` string, required — Auth provider readable ID
      - `provider_config` object, nullable — Provider-specific configuration
  - `redirect_url` string, nullable — URL to redirect to after OAuth flow completes (only used for OAuth flows)

## Response `200`

Created source connection

- SourceConnection — Complete source connection details including auth, config, sync status, and entities. This schema provides full information about a source connection, suitable for detail views and monitoring sync progress.
  - `id` string, uuid, required — Unique identifier of the source connection
  - `organization_id` string, uuid, required — Organization this connection belongs to
  - `name` string, required — Display name of the connection
  - `description` string, nullable — Optional description of the connection's purpose
  - `short_name` string, required — Source type identifier
  - `readable_collection_id` string, 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_at` string, date-time, required — When the connection was created (ISO 8601)
  - `modified_at` string, date-time, required — When the connection was last modified (ISO 8601)
  - `auth` AuthenticationDetails, required — Authentication information.
    - `method` 'direct' | 'oauth_browser' | 'oauth_token' | 'oauth_byoc' | 'auth_provider', required — Authentication methods for source connections.
    - `authenticated` boolean, required
    - `authenticated_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `auth_url` string, nullable — For pending OAuth flows
    - `auth_url_expires` string, date-time, nullable
    - `redirect_url` string, nullable
    - `claim_token` string, nullable — One-time token to verify OAuth flow ownership. Only returned when creating an OAuth browser connection.
    - `provider_readable_id` string, nullable
    - `provider_id` string, nullable
  - `config` object, nullable — Source-specific configuration values
  - `schedule` ScheduleDetails — Schedule information.
    - `cron` string, nullable
    - `next_run` string, date-time, nullable
    - `continuous` boolean
    - `cursor_field` string, nullable
    - `cursor_value` unknown
  - `sync` SyncDetails — Sync execution details.
    - `total_runs` integer
    - `successful_runs` integer
    - `failed_runs` integer
    - `last_job` SyncJobDetails — Sync job details.
      - `id` string, uuid, required
      - `status` 'created' | 'pending' | 'running' | 'completed' | 'failed' | 'cancelling' | 'cancelled', required — Sync job status enum.
      - `started_at` string, date-time, nullable
      - `completed_at` string, date-time, nullable
      - `duration_seconds` number, nullable
      - `entities_inserted` integer
      - `entities_updated` integer
      - `entities_deleted` integer
      - `entities_failed` integer
      - `error` string, nullable
  - `sync_id` string, uuid, nullable — ID of the associated sync (internal use)
  - `entities` EntitySummary — Entity state summary.
    - `total_entities` integer
    - `by_type` object
  - `federated_search` boolean — Whether this source uses federated (real-time) search instead of syncing

## Other responses

- `422` — Validation Error
- `429` — Rate Limit Exceeded

---

[API](https://skmtc.net/airweave-ai/apis/airweave.md) · [All operations](https://skmtc.net/airweave-ai/apis/airweave/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/airweave-ai/airweave/versions/bf410c28c0c6/schema)